github.com/argoproj-labs/argocd-operator@v0.10.0/docs/usage/keycloak/kubernetes.md (about)

     1  # Usage
     2  
     3  This document describes the usage of Keycloak as a Single sign-on provider for ArgoCD.
     4  
     5  The following example shows the most minimal valid manifest to create a new Argo CD cluster with keycloak as a Single sign-on provider.
     6  
     7  This guide assumes a Kubernetes cluster based on [minikube](https://minikube.sigs.k8s.io/).
     8  
     9  ## Ingress Controller
    10  
    11  Ensure that the `ingress` addon is enabled for the minikube cluster.
    12  
    13  The addon is disabled by default, enable it if necessary.
    14  
    15  ```bash
    16  minikube addons enable ingress
    17  ```
    18  
    19  Verify that the ingress Pod is running. In this example, the ingress controller is running in the `ingress-nginx` namespace.
    20  
    21  ```bash
    22  kubectl get pods -A
    23  ```
    24  
    25  ```txt
    26  NAMESPACE           NAME                                                    READY   STATUS    RESTARTS   AGE
    27  ingress-nginx       nginx-ingress-controller-6fc5bcc8c9-vg26z               1/1     Running   0          9h
    28  ```
    29  
    30  The following example shows the most minimal valid manifest to create a new Argo CD cluster with Keycloak as a Single sign-on provider.
    31  
    32  ```yaml
    33  apiVersion: argoproj.io/v1alpha1
    34  kind: ArgoCD
    35  metadata:
    36    name: example-argocd
    37    labels:
    38      example: basic
    39  spec:
    40    sso:
    41      provider: keycloak
    42    server:
    43      ingress:
    44        enabled: true
    45      insecure: true
    46  ```
    47  
    48  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.
    49  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.
    50  
    51  !!! note
    52      Argo CD server pod should be restarted after updating the `.spec.sso.keycloak.rootCA`.
    53  
    54  Please refer to the below example:
    55  
    56  ```yaml
    57  apiVersion: argoproj.io/v1alpha1
    58  kind: ArgoCD
    59  metadata:
    60    name: example-argocd
    61    labels:
    62      example: basic
    63  spec:
    64    sso:
    65      provider: keycloak
    66      keycloak:
    67       rootCA: |
    68         ---- BEGIN CERTIFICATE ----
    69         This is a dummy certificate
    70         Please place this section with appropriate rootCA
    71         ---- END CERTIFICATE ----
    72    server:
    73      ingress:
    74        enabled: true
    75  ```
    76  
    77  !!! note
    78      `.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.
    79  
    80  !!! note
    81      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. 
    82  
    83  ## Create
    84  
    85  Create a namespace for Argo CD.
    86  
    87  ```bash
    88  kubectl create ns argocd
    89  ```
    90  
    91  Create a new Argo CD Instance in the `argocd` namespace using the provided example.
    92  
    93  ```bash
    94  kubectl create -n argocd -f examples/argocd-keycloak-k8s.yaml
    95  ```
    96  
    97  !!! note
    98      `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`.
    99  
   100  ## Keycloak Instance
   101  
   102  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`.
   103  
   104  Get the Keycloak Ingress URL for Login.
   105  
   106  ```bash
   107  kubectl -n argocd get ingress keycloak
   108  ```
   109  
   110  ```txt
   111  NAME        HOST/PORT     
   112  keycloak    keycloak-ingress  
   113  ```
   114  
   115  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.
   116  
   117  Run the below commands using **root** user.
   118  
   119  ```bash
   120  echo "`minikube ip` keycloak-ingress" | sudo tee -a /etc/hosts
   121  ```
   122  
   123  Make sure an entry for `keycloak-ingress` is added in the `/etc/hosts`.
   124  
   125  ## Argo CD Login
   126  
   127  Get the Argo CD Ingress URL for Login.
   128  
   129  ```bash
   130  kubectl -n argocd get ingress example-argocd-server
   131  ```
   132  
   133  ```txt
   134  NAME                     HOST/PORT     
   135  example-argocd-server    example-argocd
   136  ```
   137  
   138  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.
   139  
   140  ```bash
   141  echo "`minikube ip` example-argocd" | sudo tee -a /etc/hosts
   142  ```
   143  
   144  Login to Argo CD using the ingress URL. You can see an option to Log in via keycloak apart from the usual ArgoCD login.
   145  
   146  ![LOGIN VIA KEYCLOAK](../../assets/keycloak/login_via_keycloak.png)
   147  
   148  Click on **LOGIN VIA KEYCLOAK**.
   149  
   150  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.
   151  
   152  !!! note
   153      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.
   154  
   155  ## RBAC
   156  
   157  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.
   158  
   159  The below example show how to grant user `foo` with email ID `foo@example.com` admin access to ArgoCD. More information regarding ArgoCD RBAC can be found [here](https://argoproj.github.io/argo-cd/operator-manual/rbac/)
   160  
   161  ```yaml
   162  policy.csv: |
   163    g, foo@example.com, role:admin
   164  ```
   165  
   166  ### Uninstall
   167  
   168  You can delete the Keycloak resources and its relevant configuration by removing the SSO field from ArgoCD Custom Resource Spec.
   169  
   170  Example ArgoCD after removing the SSO field should look something like this.
   171  
   172  ```yaml
   173  apiVersion: argoproj.io/v1alpha1
   174  kind: ArgoCD
   175  metadata:
   176    name: example-argocd
   177    labels:
   178      example: basic
   179  spec:
   180    server:
   181      ingress:
   182        enabled: true
   183  ```