Deploy using GitOps and Argo CD

Deploy Che declaratively through Argo CD so that every configuration change is tracked in Git, auditable, and automatically reconciled on the cluster.

This page is for platform administrators who install, configure, and manage Che on Kubernetes clusters. To learn more about common roles and example tasks referenced in Che documentation, see Common user roles and tasks.

With this method, you store the Operator subscription and CheCluster configuration in a Git repository. Argo CD monitors the repository and applies changes to the cluster automatically. You manage Che through Git commits instead of direct cluster commands.

Prerequisites

You have a Kubernetes or Kubernetes cluster with administrative access.
You have Argo CD installed on the cluster. See Argo CD Getting Started.
You have an active kubectl session with administrative permissions to the cluster.
You have a Git repository accessible from the cluster (GitHub, GitLab, Bitbucket, or an internal Git server).

Procedure

In your Git repository, create a directory for the Che manifests. The directory contains three files: the Operator subscription, the CheCluster custom resource, and a Kustomize configuration.
Repository structure
```
<your-gitops-repo>/
└── che/
    ├── subscription.yaml
    ├── checluster.yaml
    └── kustomization.yaml
```

Create the subscription.yaml file with the namespace and Operator subscription:

apiVersion: v1
kind: Namespace
metadata:
  name: eclipse-che
---
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: eclipse-che
  namespace: openshift-operators
spec:
  channel: stable
  installPlanApproval: Automatic
  name: eclipse-che
  source: community-operators
  sourceNamespace: openshift-marketplace

On Kubernetes clusters without OLM, install the Che Operator using Helm or chectl instead of a Subscription.

Create the checluster.yaml file with the Che instance configuration:

apiVersion: org.eclipse.che/v2
kind: CheCluster
metadata:
  name: eclipse-che
  namespace: eclipse-che
spec:
  components:
    cheServer:
      debug: false
      logLevel: INFO
    metrics:
      enable: true
    pluginRegistry:
      openVSXURL: https://open-vsx.org
  devEnvironments:
    startTimeoutSeconds: 300
    defaultEditor: che-incubator/che-code/latest
    defaultNamespace:
      autoProvision: true
      template: <username>-che
    storage:
      pvcStrategy: per-user

Create the kustomization.yaml file:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - subscription.yaml
  - checluster.yaml

Commit and push the files to your Git repository.

Grant the Argo CD service account the permissions required to create namespaces and install Operators:

$ kubectl apply -f - <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: argocd-cluster-admin
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
  - kind: ServiceAccount
    name: argocd-application-controller
    namespace: argocd
EOF

Adjust the ServiceAccount name and namespace to match your Argo CD installation.

Create the Argo CD Application resource that points to your Git repository:

$ kubectl apply -f - <<EOF
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: che
  namespace: argocd
spec:
  project: default
  source:
    repoURL: <your-git-repo-url>
    targetRevision: main
    path: che
  destination:
    server: https://kubernetes.default.svc
  syncPolicy:
    automated:
      selfHeal: true
      prune: true
    retry:
      limit: 10
      backoff:
        duration: 30s
        factor: 2
        maxDuration: 5m
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true
      - SkipDryRunOnMissingResource=true
EOF

SkipDryRunOnMissingResource: Required because the CheCluster custom resource definition (CRD) does not exist until the Operator installs it. This option tells Argo CD to skip validation for unknown resource types and apply them directly.
selfHeal: Reverts manual changes on the cluster to match the Git repository state.

Wait for Argo CD to sync the resources. The Operator installs first, registers the CheCluster CRD, and then Argo CD applies the CheCluster custom resource.

Verification

Verify that the Argo CD Application reports Synced and Healthy:

$ kubectl get application che -n argocd \
    -o jsonpath='{.status.sync.status}{" "}{.status.health.status}'

Expected output: Synced Healthy

Verify that the CheCluster is active:

$ kubectl get checluster eclipse-che -n eclipse-che \
    -o jsonpath='{.status.chePhase}'

Expected output: Active

Retrieve the Che dashboard URL and open it in a browser:

$ kubectl get checluster eclipse-che -n eclipse-che \
    -o jsonpath='{.status.cheURL}'

Troubleshooting

Sync fails with "CheCluster CRD not found": Verify that the Argo CD Application includes SkipDryRunOnMissingResource=true in the syncOptions.
Sync retries but CheCluster is not created: The Operator may still be installing. Wait for the ClusterServiceVersion to reach Succeeded:
```
$ kubectl get csv -A | grep eclipse-che
```

Additional resources