github.com/argoproj-labs/argocd-operator@v0.10.0/docs/usage/basics.md (about) 1 # Usage Basics 2 3 See the [ArgoCD Reference][argocd_reference] for the full list of properties and defaults to configure the Argo CD cluster. 4 5 The following example shows the most minimal valid manifest to create a new Argo CD cluster with the default configuration. 6 7 ```yaml 8 apiVersion: argoproj.io/v1alpha1 9 kind: ArgoCD 10 metadata: 11 name: example-argocd 12 labels: 13 example: basic 14 spec: {} 15 ``` 16 17 ## Create 18 19 Create a new Argo CD cluster in the `argocd` namespace using the provided basic example. 20 21 ```bash 22 kubectl create -n argocd -f examples/argocd-basic.yaml 23 ``` 24 25 There will be several Argo CD resources created that should be familiar to anyone who has deployed Argo CD. 26 27 ```bash 28 kubectl get cm,secret,deploy -n argocd 29 ``` 30 31 Some unrelated items have been removed for clarity. 32 33 ```bash 34 NAME DATA AGE 35 configmap/argocd-cm 14 2m9s 36 configmap/argocd-rbac-cm 3 2m9s 37 configmap/argocd-ssh-known-hosts-cm 1 2m9s 38 configmap/argocd-tls-certs-cm 0 2m9s 39 40 NAME TYPE DATA AGE 41 secret/argocd-secret Opaque 5 2m9s 42 secret/example-argocd-ca kubernetes.io/tls 2 2m9s 43 secret/example-argocd-cluster Opaque 1 2m9s 44 secret/example-argocd-tls kubernetes.io/tls 2 2m9s 45 46 NAME READY UP-TO-DATE AVAILABLE AGE 47 deployment.apps/example-argocd-application-controller 1/1 1 1 2m8s 48 deployment.apps/example-argocd-dex-server 1/1 1 1 2m8s 49 deployment.apps/example-argocd-redis 1/1 1 1 2m8s 50 deployment.apps/example-argocd-repo-server 1/1 1 1 2m8s 51 deployment.apps/example-argocd-server 1/1 1 1 2m8s 52 ``` 53 54 ### ConfigMaps 55 56 There are several ConfigMaps that are used by Argo CD. The `argocd-server` component reads and writes to these 57 ConfigMaps based on user interaction with the web UI or via the `argocd` CLI. It is worth noting that the name 58 `argocd-cm` is hard-coded, thus limiting us to one Argo CD cluster per namespace to avoid conflicts. 59 60 ```bash 61 NAME DATA AGE 62 configmap/argocd-cm 14 33s 63 configmap/argocd-rbac-cm 3 33s 64 configmap/argocd-ssh-known-hosts-cm 1 33s 65 configmap/argocd-tls-certs-cm 0 33s 66 ``` 67 68 The operator will create these ConfigMaps for the cluster and set the initial values based on properties on the 69 `ArgoCD` custom resource. 70 71 ### Secrets 72 73 There is a Secret that is used by Argo CD named `argocd-secret`. The `argocd-server` component reads this secret to 74 obtain the admin password for authentication. NOTE: Upon initial deployment, the initial password for the `admin` user is stored in the `argocd-cluster` secret instead. 75 76 This Secret is managed by the operator and should not be changed directly. 77 78 ``` bash 79 NAME TYPE DATA AGE 80 secret/argocd-secret Opaque 5 33s 81 ``` 82 83 Several other Secrets are also managed by the operator. 84 85 ``` bash 86 NAME TYPE DATA AGE 87 secret/example-argocd-ca kubernetes.io/tls 2 33s 88 secret/example-argocd-cluster Opaque 1 33s 89 secret/example-argocd-tls kubernetes.io/tls 2 33s 90 ``` 91 92 The cluster Secret contains the admin password for authenticating with Argo CD. 93 94 ```bash 95 apiVersion: v1 96 data: 97 admin.password: ... 98 kind: Secret 99 metadata: 100 labels: 101 app.kubernetes.io/name: example-argocd-cluster 102 app.kubernetes.io/part-of: argocd 103 example: basic 104 name: example-argocd-cluster 105 namespace: argocd 106 type: Opaque 107 ``` 108 109 The operator will watch for changes to the `admin.password` value. When a change is made the password is synchronized to 110 Argo CD automatically. 111 112 Fetch the admin password from the cluster Secret. 113 114 ``` bash 115 kubectl -n argocd get secret example-argocd-cluster -o jsonpath='{.data.admin\.password}' | base64 -d 116 ``` 117 118 To change the admin password you'll need to modify the cluster secret like this: 119 120 ```shell 121 $ kubectl -n argocd patch secret example-argocd-cluster \ 122 -p '{"stringData": { 123 "admin.password": "newpassword2021" 124 }}' 125 ``` 126 127 ### Deployments 128 129 There are several Deployments that are managed by the operator for the different components that make up an Argo CD cluster. 130 131 ``` bash 132 NAME READY UP-TO-DATE AVAILABLE AGE 133 deployment.apps/example-argocd-application-controller 1/1 1 1 2m8s 134 deployment.apps/example-argocd-dex-server 1/1 1 1 2m8s 135 deployment.apps/example-argocd-redis 1/1 1 1 2m8s 136 deployment.apps/example-argocd-repo-server 1/1 1 1 2m8s 137 deployment.apps/example-argocd-server 1/1 1 1 2m8s 138 ``` 139 140 The deployments are exposed via Services that can be used to access the Argo CD cluster. 141 142 ### Services 143 144 The ArgoCD Server component should be available via a Service. 145 146 ```bash 147 kubectl get svc -n argocd 148 ``` 149 ```bash 150 NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE 151 example-argocd-dex-server ClusterIP 10.105.36.155 <none> 5556/TCP,5557/TCP 2m28s 152 example-argocd-metrics ClusterIP 10.102.88.192 <none> 8082/TCP 2m28s 153 example-argocd-redis ClusterIP 10.101.29.123 <none> 6379/TCP 2m28s 154 example-argocd-repo-server ClusterIP 10.103.229.32 <none> 8081/TCP,8084/TCP 2m28s 155 example-argocd-server ClusterIP 10.100.186.222 <none> 80/TCP,443/TCP 2m28s 156 example-argocd-server-metrics ClusterIP 10.100.185.144 <none> 8083/TCP 2m28s 157 argocd-operator-metrics ClusterIP 10.97.124.166 <none> 8383/TCP,8686/TCP 23m 158 ``` 159 160 ## Server API & UI 161 162 The Argo CD server component exposes the API and UI. The operator creates a Service to expose this component and 163 can be accessed through the various methods available in Kubernetes. 164 165 Follow the ArgoCD [Getting Started Guide](https://argoproj.github.io/argo-cd/getting_started/#creating-apps-via-ui) to 166 create a new application from the UI. 167 168 ### Local Machine 169 170 In the most simple case, the Service port can be forwarded to the local machine. 171 172 ```bash 173 kubectl -n argocd port-forward service/example-argocd-server 8443:443 174 ``` 175 176 The server UI should be available at [https://localhost:8443/](https://localhost:8443/). 177 178 ### Ingress 179 180 See the [ingress][docs_ingress] documentation for steps to enable and use the Ingress support provided by the operator. 181 182 ### OpenShift Route 183 184 See the [routes][docs_routes] documentation for steps to configure the Route support provided by the operator. 185 186 [docs_ingress]:./ingress.md 187 [docs_routes]:./routes.md 188 [argocd_reference]:../reference/argocd.md 189 190 ### Default Permissions provided to Argo CD instance 191 192 By default Argo CD instance is provided the following permissions 193 194 * Argo CD instance is provided with ADMIN privileges for the namespace it is installed in. For instance, if an Argo CD instance is deployed in **foo** namespace, it will have **ADMIN privileges** to manage resources for that namespace. 195 196 * Argo CD is provided the following cluster scoped permissions because Argo CD requires cluster-wide read privileges on resources to function properly. (Please see [RBAC](https://argo-cd.readthedocs.io/en/stable/operator-manual/security/#cluster-rbac) section for more details.) 197 198 ```yaml 199 apiVersion: rbac.authorization.k8s.io/v1 200 kind: Role 201 metadata: 202 labels: 203 app.kubernetes.io/managed-by: <argocd-instance-name> 204 app.kubernetes.io/name: <argocd-instance-name> 205 app.kubernetes.io/part-of: argocd 206 name: <argocd-instance-name>-argocd-application-controller 207 namespace: <argocd-instance-namespace> 208 rules: 209 - apiGroups: 210 - '*' 211 resources: 212 - '*' 213 verbs: 214 - '*' 215 ``` 216 217 ## Cluster Scoped Instance 218 219 The Argo CD instance created above can also be used to manage the cluster scoped resources by adding the namespace of the Argo CD instance to the `ARGOCD_CLUSTER_CONFIG_NAMESPACES` environment variable of subscription resource as shown below. 220 221 ```yml 222 apiVersion: operators.coreos.com/v1alpha1 223 kind: Subscription 224 metadata: 225 name: argocd-operator 226 spec: 227 config: 228 env: 229 - name: ARGOCD_CLUSTER_CONFIG_NAMESPACES 230 value: <list of namespaces of cluster-scoped Argo CD instances> 231 channel: alpha 232 name: argocd-operator 233 source: argocd-catalog 234 sourceNamespace: olm 235 ``` 236 237 ### In-built permissions for cluster configuration 238 239 Argo CD is granted the following permissions using a cluster role when it is configured as cluster-scoped instance. **Argo CD is not granted cluster-admin**. 240 241 Please note that these permissions are in addition to the `admin` privileges that Argo CD has to the namespace in which it is installed. 242 243 ```yaml 244 kind: ClusterRole 245 apiVersion: rbac.authorization.k8s.io/v1 246 metadata: 247 name: <argocd-instance-name>-<namespace>-argocd-application-controller 248 labels: 249 app.kubernetes.io/managed-by: <argocd-instance-namespace> 250 app.kubernetes.io/name: <argocd-instance-namespace> 251 app.kubernetes.io/part-of: argocd 252 rules: 253 - verbs: 254 - '*' 255 apiGroups: 256 - '*' 257 resources: 258 - '*' 259 ``` 260 261 ### Additional permissions 262 263 Users can extend the permissions granted to Argo CD application controller by creating cluster roles with additional permissions and then a new cluster role binding to associate them to the service account. 264 265 For example, user can extend the permissions for an Argo CD instance to be able to list the secrets for all namespaces by creating the below resources. 266 267 #### Cluster Role 268 269 ```yaml 270 apiVersion: rbac.authorization.k8s.io/v1 271 kind: ClusterRole 272 metadata: 273 # "namespace" omitted since ClusterRoles are not namespaced 274 name: secrets-cluster-role 275 rules: 276 - apiGroups: [""] #specifies core api groups 277 resources: ["secrets"] 278 verbs: ["*"] 279 ``` 280 281 #### Cluster Role Binding 282 283 ```yaml 284 apiVersion: rbac.authorization.k8s.io/v1 285 # This cluster role binding allows Service Account to read secrets in any namespace. 286 kind: ClusterRoleBinding 287 metadata: 288 name: read-secrets-global 289 roleRef: 290 apiGroup: rbac.authorization.k8s.io 291 kind: ClusterRole 292 name: secrets-cluster-role # Name of cluster role to be referenced 293 subjects: 294 - kind: ServiceAccount 295 name: <argocd-instance-service-account-name> 296 namespace: <argocd-instance-namespace> 297 ```