argoproj-labs · olivergondza · Aug 19, 2025 · Aug 19, 2025
diff --git a/docs/developer-guide/development.md b/docs/developer-guide/development.md
@@ -129,7 +129,7 @@ For more infomation see [build operator images to test on a cluster.](https://ar
 
 Once the operator is installed, you would need to configure an ArgoCD instance that the operator would manage. The sample instance configuration is below:
 ``` yaml
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: example-argocd

diff --git a/docs/reference/argocd.md b/docs/reference/argocd.md
@@ -60,7 +60,7 @@ This property maps directly to the `application.instanceLabelKey` field in the `
 The following example sets the default value in the `argocd-cm` ConfigMap using the `ApplicationInstanceLabelKey` property on the `ArgoCD` resource.
 
 ``` yaml
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: example-argocd

diff --git a/docs/usage/aggregated_roles.md b/docs/usage/aggregated_roles.md
@@ -5,7 +5,7 @@ Using an aggregated cluster role enables users to easily add their own permissio
 A user can enable creation of aggregated ClusterRole by setting `argocd.spec.aggregatedClusterRoles` field to `true`.
 
 ```yaml
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: example-argocd
@@ -121,4 +121,4 @@ rules:
 
 Let's summarize this example. The `argocd-argocd-argocd-application-controller` cluster role inherits permissions from two cluster role which are `argocd-argocd-argocd-application-controller-view` for view permissions and `argocd-argocd-argocd-application-controller-admin` for admin permission. These three are operator managed. Now `argocd-argocd-argocd-application-controller-admin` inherits permissions from `my-cluster-role` which is a user defined cluster role.  
 
-For more details on aggregated cluster role, check the [documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles).
+For more details on aggregated cluster role, check the [documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#aggregated-clusterroles).
diff --git a/docs/usage/apps-in-any-namespace.md b/docs/usage/apps-in-any-namespace.md
@@ -15,7 +15,7 @@ In order to enable this feature, specify the namespaces where Argo CD should man
 
 ## Enable application creation in a specific namespace
 ```yaml
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: example-argocd
@@ -30,7 +30,7 @@ In this example:
 ## Enable application creation in namespaces matching a glob pattern
 
 ```yaml
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: example-argocd-wildcard-pattern
@@ -45,7 +45,7 @@ In this example:
 ## Enable application creation in all namespaces
 
 ```yaml
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: example-argocd-all-namespaces

diff --git a/docs/usage/basics.md b/docs/usage/basics.md
@@ -5,7 +5,7 @@ See the [ArgoCD Reference][argocd_reference] for the full list of properties and
 The following example shows the most minimal valid manifest to create a new Argo CD cluster with the default configuration.
 
 ```yaml
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: example-argocd

diff --git a/docs/usage/config_management_2.0.md b/docs/usage/config_management_2.0.md
@@ -28,7 +28,7 @@ data:
       allowConcurrency: true
       lockRepo: true
 ---
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: example-argocd

diff --git a/docs/usage/custom_roles.md b/docs/usage/custom_roles.md
@@ -50,7 +50,7 @@ as needed and have them applied across all cluster scoped instances. For example
 These customized ClusterRoles need to be created and referred in ClusterRoleBinding by admin. A user can disable creation of default ClusterRoles by setting `ArgoCD.Spec.DefaultClusterScopedRoleDisabled` field to `true`.
 
 ```yaml
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: example-argocd
@@ -60,4 +60,4 @@ spec:
   defaultClusterScopedRoleDisabled: true
 ```
 
-When `defaultClusterScopedRoleDisabled` is `true`, the default ClusterRole/ClusterRoleBindings for the Argo CD instance will not be created, and the administrative user is free to create and customize these independent of the operator. The field can later be set to `false`, to recreate these resources, if needed.
+When `defaultClusterScopedRoleDisabled` is `true`, the default ClusterRole/ClusterRoleBindings for the Argo CD instance will not be created, and the administrative user is free to create and customize these independent of the operator. The field can later be set to `false`, to recreate these resources, if needed.
diff --git a/docs/usage/customization.md b/docs/usage/customization.md
@@ -7,7 +7,7 @@ See [upstream documentation](https://argo-cd.readthedocs.io/en/stable/operator-m
 Both init containers and volumes can be added to the repo server using the `ArgoCD` custom resource
 
 ```yaml
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: argocd-sample

diff --git a/docs/usage/dex.md b/docs/usage/dex.md
@@ -25,7 +25,7 @@ Dex configuration has moved to `.spec.sso` in release v0.4.0. Dex can be enabled
 An example of correctly configured dex would look as follows:
 
 ```yaml
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: example-argocd
@@ -43,7 +43,7 @@ The below section describes how to configure Argo CD SSO using OpenShift connect
 The `openShiftOAuth` property can be used to trigger the operator to auto configure the built-in OpenShift OAuth server. The `groups` property is used to mandate users to be part of one or all the groups in the groups list. The RBAC `Policy` property is used to give the admin role in the Argo CD cluster to users in the OpenShift `cluster-admins` group.
 
 ``` yaml
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: example-argocd
@@ -88,7 +88,7 @@ You will very likely want to restrict logins to one or more GitHub organization.
 `connectors.config.orgs` list, add one or more GitHub organizations. Any member of the org will then be able to login to Argo CD to perform management tasks.
 
 ``` yaml
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: example-argocd
@@ -122,7 +122,7 @@ The below section describes how to configure Argo CD's Dex to accept authenticat
 In the `sso.dex.env` key, add the environment variable as shown in the [example manifests for authenticating against Argo CD's Dex](https://argoproj.github.io/argo-workflows/argo-server-sso-argocd/#example-manifests-for-authenticating-against-argo-cds-dex-kustomize).
 
 ``` yaml
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: example-argocd

diff --git a/docs/usage/extra-config.md b/docs/usage/extra-config.md
@@ -18,7 +18,7 @@ When `ExtraConfig` is set, the entries specified are reconciled to the live Argo
 ## Example
 
 ```yaml
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: example-argocd

diff --git a/docs/usage/ha/redis.md b/docs/usage/ha/redis.md
@@ -8,7 +8,7 @@ To enable HA for an Argo CD cluster, include the `ha` section in the `ArgoCD` Cu
     When `ha` is enabled, changes to `.spec.redis.resources` doesn't have any effect. Redis resource limits can be set using `.spec.ha.resources`.
 
 ``` yaml
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: example-argocd

diff --git a/docs/usage/ingress.md b/docs/usage/ingress.md
@@ -79,7 +79,7 @@ Create an ArgoCD resource that enables ingress. Note that in this case we run th
 terminate TLS at the Ingress controller. See `examples/argocd-ingress.yaml` for this example.
 
 ```yaml
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: example-argocd

diff --git a/docs/usage/insights.md b/docs/usage/insights.md
@@ -65,7 +65,7 @@ prometheus-operator-7f6dfb7686-wb9h2  1/1     Running   0          9m4s
 The following example shows how to enable Prometheus to provide operator insights. This example also enables Ingress for accessing the cluster resources.
 
 ``` yaml
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: example-argocd
@@ -118,7 +118,7 @@ example-argocd-prometheus   <none>   example-argocd-prometheus   192.168.39.68
 For OpenShift clusters, Routes will be created when route is enabled as shown in the below example.
 
 ``` yaml
-apiVersion: argoproj.io/v1alpha1
+apiVersion: argoproj.io/v1beta1
 kind: ArgoCD
 metadata:
   name: example-argocd

diff --git a/docs/usage/keycloak/kubernetes.md b/docs/usage/keycloak/kubernetes.md
@@ -0,0 +1,183 @@
+# Usage
+
+This document describes the usage of Keycloak as a Single sign-on provider for ArgoCD.
+
+The following example shows the most minimal valid manifest to create a new Argo CD cluster with keycloak as a Single sign-on provider.
+
+This guide assumes a Kubernetes cluster based on [minikube](https://minikube.sigs.k8s.io/).
+
+## Ingress Controller
+
+Ensure that the `ingress` addon is enabled for the minikube cluster.
+
+The addon is disabled by default, enable it if necessary.
+
+```bash
+minikube addons enable ingress
+```
+
+Verify that the ingress Pod is running. In this example, the ingress controller is running in the `ingress-nginx` namespace.
+
+```bash
+kubectl get pods -A
+```
+
+```txt
+NAMESPACE           NAME                                                    READY   STATUS    RESTARTS   AGE
+ingress-nginx       nginx-ingress-controller-6fc5bcc8c9-vg26z               1/1     Running   0          9h
+```
+
+The following example shows the most minimal valid manifest to create a new Argo CD cluster with Keycloak as a Single sign-on provider.
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: ArgoCD
+metadata:
+  name: example-argocd
+  labels:
+    example: basic
+spec:
+  sso:
+    provider: keycloak
+  server:
+    ingress:
+      enabled: true
+    insecure: true
+```
+
+If your keycloak is setup with a certificate which is not signed by one of the well known certificate authorities you can provide a custom certificate which will be used in verifying the Keycloak's TLS certificate when communicating with it.
+Add the rootCA to your Argo CD custom resource `.spec.sso.keycloak.rootCA` field. The operator reconciles to this change and updates the `oidc.config` in `argocd-cm` configmap with the PEM encoded root certificate.
+
+!!! note
+    Argo CD server pod should be restarted after updating the `.spec.sso.keycloak.rootCA`.
+
+Please refer to the below example:
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: ArgoCD
+metadata:
+  name: example-argocd
+  labels:
+    example: basic
+spec:
+  sso:
+    provider: keycloak
+    keycloak:
+     rootCA: |
+       ---- BEGIN CERTIFICATE ----
+       This is a dummy certificate
+       Please place this section with appropriate rootCA
+       ---- END CERTIFICATE ----
+  server:
+    ingress:
+      enabled: true
+```
+
+!!! note
+    `.spec.sso.Image`, `.spec.sso.Version`, `.spec.sso.Resources` and `.spec.sso.verifyTLS` fields are no longer supported in Argo CD operator v0.8.0 onwards. Please use equivalent fields under `.spec.sso.keycloak` to configure your keycloak instance.
+
+!!! note
+    If you test the operator locally using `make run`, please add `.spec.sso.keycloak.verifyTLS: false` to your Argo CD CR. Specifying conflicting information in both specs will result in errors. 
+
+## Create
+
+Create a namespace for Argo CD.
+
+```bash
+kubectl create ns argocd
+```
+
+Create a new Argo CD Instance in the `argocd` namespace using the provided example.
+
+```bash
+kubectl create -n argocd -f examples/argocd-keycloak-k8s.yaml
+```
+
+!!! note
+    `verifyTLS` option should be set to `true` if you want to enable strict TLS validation in production. If you are running operator on your machine using `operator-sdk run local`, `verifyTLS` should be set to `false`.
+
+## Keycloak Instance
+
+The above configuration creates a Keycloak instance and its relevant resources along with the Argo CD resources. The default credentials for Keycloak is `admin/admin`.
+
+Get the Keycloak Ingress URL for Login.
+
+```bash
+kubectl -n argocd get ingress keycloak
+```
+
+```txt
+NAME        HOST/PORT     
+keycloak    keycloak-ingress  
+```
+
+If you running Kubernetes on minikube. Add keycloak hostname to the `/etc/hosts` file on the local machine, which is needed to access the services running locally on minikube.
+
+Run the below commands using **root** user.
+
+```bash
+echo "`minikube ip` keycloak-ingress" | sudo tee -a /etc/hosts
+```
+
+Make sure an entry for `keycloak-ingress` is added in the `/etc/hosts`.
+
+## Argo CD Login
+
+Get the Argo CD Ingress URL for Login.
+
+```bash
+kubectl -n argocd get ingress example-argocd-server
+```
+
+```txt
+NAME                     HOST/PORT     
+example-argocd-server    example-argocd
+```
+
+As explained above, add `example-argocd` hostname to the `/etc/hosts` file on the local machine, which is needed to access the services running locally on minikube.
+
+```bash
+echo "`minikube ip` example-argocd" | sudo tee -a /etc/hosts
+```
+
+Login to Argo CD using the ingress URL. You can see an option to Log in via keycloak apart from the usual ArgoCD login.
+
+![LOGIN VIA KEYCLOAK](../../assets/keycloak/login_via_keycloak.png)
+
+Click on **LOGIN VIA KEYCLOAK**.
+
+You can [create keycloak users](https://www.keycloak.org/docs/latest/getting_started/#creating-a-user) by logging in to keycloak admin console using the Keycloak admin credentials and Keycloak Ingress URL.
+
+!!! note
+    Keycloak instance takes 2-3 minutes to be up and running. You will see the option **LOGIN VIA KEYCLOAK** only after the keycloak instance is up.
+
+## RBAC
+
+By default any user logged into ArgoCD will have read-only access. User/Group level access can be managed by updating the argocd-rbac-cm configmap.
+
+The below example show how to grant user `foo` with email ID `[email protected]` admin access to ArgoCD. More information regarding ArgoCD RBAC can be found [here](https://argoproj.github.io/argo-cd/operator-manual/rbac/)
+
+```yaml
+policy.csv: |
+  g, [email protected], role:admin
+```
+
+### Uninstall
+
+You can delete the Keycloak resources and its relevant configuration by removing the SSO field from ArgoCD Custom Resource Spec.
+
+Example ArgoCD after removing the SSO field should look something like this.
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: ArgoCD
+metadata:
+  name: example-argocd
+  labels:
+    example: basic
+spec:
+  server:
+    ingress:
+      enabled: true
+```