Skip to content

Quickstart (Operator - recommended)

This is the shortest path to first reconcile success with the Kubernetes Operator.

Prerequisites

  • A Kubernetes cluster with kubectl access
  • A namespace for the Operator (examples use declarest-system)
  • A Git repository that stores DeclaREST resource files (desired state)
  • Managed Server API endpoint + auth credentials
  • Dynamic PVC provisioning, or existing PVCs

1. Install CRDs and Operator

Choose one released install manifest:

Manifest What it installs Depends on Use it when
install.yaml CRDs, RBAC, operator manager Nothing beyond Kubernetes You want the fastest path to first reconcile success
install-admission-certmanager.yaml install.yaml plus validating admission webhooks cert-manager Recommended for most non-OpenShift production clusters
install-admission-openshift.yaml install.yaml plus validating admission webhooks OpenShift serving cert support Recommended on OpenShift

Admission-enabled manifests reject invalid CRs earlier, at create/update time. The base install.yaml keeps cluster dependencies minimal and is the shortest quickstart path.

VERSION=v0.3.8
kubectl create namespace declarest-system
kubectl apply -f "https://github.com/crmarques/declarest/releases/download/${VERSION}/install.yaml"

That installs the CRDs and deploys the Operator manager from the tagged release.

If you want admission validation from the start, swap the filename in the URL:

  • install-admission-certmanager.yaml on standard Kubernetes clusters with cert-manager
  • install-admission-openshift.yaml on OpenShift

2. Create required Secrets

Create secrets referenced by CRs (adjust names/keys/values for your environment):

kubectl -n declarest-system create secret generic repository-credentials \
  --from-literal=token='<git-token>' \
  --from-literal=webhook-secret='<webhook-secret>'

kubectl -n declarest-system create secret generic managed-server-auth \
  --from-literal=token='<api-token>'

kubectl -n declarest-system create secret generic secret-store-file \
  --from-literal=passphrase='<strong-passphrase>'

3. Apply minimal CRs

For first reconcile success, use a manifest like this. The files under config/samples/ are reference templates and still require environment-specific edits before you apply them.

apiVersion: declarest.io/v1alpha1
kind: ResourceRepository
metadata:
  name: demo-repository
  namespace: declarest-system
spec:
  type: git
  pollInterval: 1m
  git:
    url: https://github.com/example/declarest-resources.git
    branch: main
    auth:
      tokenRef:
        name: repository-credentials
        key: token
  storage:
    pvc:
      accessModes: ["ReadWriteOnce"]
      requests:
        storage: 1Gi
---
apiVersion: declarest.io/v1alpha1
kind: ManagedServer
metadata:
  name: demo-managed-server
  namespace: declarest-system
spec:
  http:
    baseURL: https://api.example.com
    auth:
      customHeaders:
        - header: Authorization
          prefix: Bearer
          valueRef:
            name: managed-server-auth
            key: token
---
apiVersion: declarest.io/v1alpha1
kind: SecretStore
metadata:
  name: demo-secret-store
  namespace: declarest-system
spec:
  file:
    path: /var/lib/declarest/secrets/secrets.json
    encryption:
      passphraseRef:
        name: secret-store-file
        key: passphrase
    storage:
      pvc:
        accessModes: ["ReadWriteOnce"]
        requests:
          storage: 1Gi
---
apiVersion: declarest.io/v1alpha1
kind: SyncPolicy
metadata:
  name: demo-sync
  namespace: declarest-system
spec:
  resourceRepositoryRef:
    name: demo-repository
  managedServerRef:
    name: demo-managed-server
  secretStoreRef:
    name: demo-secret-store
  source:
    path: /customers
    recursive: true
  sync:
    force: false
    prune: false
  suspend: false

Apply it:

kubectl apply -f quickstart-operator.yaml

spec.storage.pvc.accessModes is required when you ask DeclaREST to create a PVC. The operator does not default it because valid access modes depend on your cluster storage class.

4. Confirm health and reconcile

kubectl -n declarest-system get resourcerepositories,managedservers,secretstores,syncpolicies
kubectl -n declarest-system describe syncpolicy demo-sync
kubectl -n declarest-system logs deploy/declarest-operator -c manager --tail=200

Look for Ready=True conditions and non-empty lastFetchedRevision / lastAppliedRepoRevision in status.

5. Prove Git commit -> state change

  1. Change one resource file in your Git repo under /customers/....
  2. Commit and push.
  3. Wait one reconcile interval (or trigger a reconcile by changing SyncPolicy).
  4. Check status again:
kubectl -n declarest-system get syncpolicy demo-sync -o yaml

You should see the new attempted/applied revision and updated sync timestamps.

Next steps