feat(operator): make running ZITADEL easy (#1562)

* docs: describe crd mode * docs: fix links * docs: fix commands and crdb resources * feat: add configure command * chore: use latest ORBOS * chore: use latest ORBOS * docs: start gitops docs * fix: compile * chore: fix build script path * chore: remove redundant prebuild * chore: add configure.go * docs: describe gitops mode * docs: point template links to main branch * docs: fix versions * feat: initialize empty keys * feat: reconfigure running ZITADEL * docs: describe crd mode * docs: fix links * docs: fix commands and crdb resources * feat: add configure command * chore: use latest ORBOS * chore: use latest ORBOS * docs: start gitops docs * fix: compile * chore: fix build script path * chore: remove redundant prebuild * chore: add configure.go * docs: describe gitops mode * docs: point template links to main branch * docs: fix versions * feat: initialize empty keys * feat: reconfigure running ZITADEL * test: fix * docs: keys are generated with configure * docs: remove keys from template * chore: pass compile time data * chore: use latest ORBOS * fix: when in-cluster, use in-cluster k8s client * fix: try in-cluster config if kubeconfig is empty * fix: reduce unneeded side effects for configure command * docs: boom version * chore: use latest ORBOS * chore: use latest ORBOS * initial commit * inital changes * commit WIP Information Architecture * commit a working state * add static assets and project * add org and fix img names * add plausible * remove img * change sidebar to easier mgmt * add openid oauth and domains * lint md * quickstarts * add auth flow * identity brokering * remove site * fix broken links * extend footer * extend readme * fix: styling * fix: zitadel logo on index * styling * border * fix: nav * fix: nav * fix: index * fix: corrected zitadelctl examples * fix: rename architecture to concepts * fix: introductions * fix: introductions * fix: introductions * docs: cli r/w secrets examples * docs: finish ZITADEL Enterprise Cloud * docs: mention ZITADEL Enterprise Cloud tier * docs: comment configuration options * docs: fix broken links * docs: move some introduction texts around * docs: twilio and email are mandatory * docs: download latest binaries Co-authored-by: Florian Forster <florian@caos.ch> Co-authored-by: fabi <fabienne.gerschwiler@gmail.com> Co-authored-by: Livio Amstutz <livio.a@gmail.com> Co-authored-by: Stefan Benz <stefan@caos.ch>
2025-12-04 22:13:36 +00:00 · 2021-04-22 18:43:34 +02:00
parent 06281b5ccb
commit c0878e4509
73 changed files with 1015 additions and 536 deletions
--- a/docs/docs/guides/installation/crd.md
+++ b/docs/docs/guides/installation/crd.md
@@ -0,0 +1,60 @@
+---
+title: CRD Mode on an existing Kubernetes cluster
+---
+
+:::tip What I need
+I'd like to see an automatically operated ZITADEL instance running on my own [Kubernetes](https://kubernetes.io/) cluster
+:::
+
+First, download the template configuration files [database.yml](./templates/crd/database.yml) and [zitadel.yml](./templates/crd/zitadel.yml). Then adjust the values in database.yml and zitadel.yml to match your environment. Especially the values for the domain, cluster DNS, storage class, email and Twilio are important.  
+
+```bash
+# Download the zitadelctl binary
+curl -s https://api.github.com/repos/caos/zitadel/releases/latest | grep "browser_download_url.*zitadelctl-$(uname | awk '{print tolower($0)}')-amd64" | cut -d '"' -f 4 | sudo wget -i - -O /usr/local/bin/zitadelctl && sudo chmod +x /usr/local/bin/zitadelctl && sudo chown $(id -u):$(id -g) /usr/local/bin/zitadelctl
+sudo chmod +x /usr/local/bin/zitadelctl
+sudo chown $(id -u):$(id -g) /usr/local/bin/zitadelctl
+
+# Deploy the operators to the current-context of your ~/.kube/config file
+zitadelctl takeoff
+
+# As soon as the configuration is applied, the operators start their work
+kubectl apply --filename ./database.yml,./zitadel.yml
+
+# Write the encryption keys
+wget https://raw.githubusercontent.com/caos/zitadel/main/site/docs/start/templates/example_keys && zitadelctl writesecret zitadel.keys.existing --file ./example_keys
+
+# Write the Twiilio sender ID and auth token so that ZITADEL is able to send your users SMS.
+TWILIO_SID=<My Twilio Sender ID>
+TWILIO_AUTH_TOKEN=<My Twilio auth token>
+zitadelctl writesecret zitadel.twiliosid.existing --value $SID
+zitadelctl writesecret zitadel.twilioauthtoken.existing --value $TWILIO_AUTH_TOKEN
+
+# Write your email relays app key so that ZITADEL is able to verify your users email addresses
+EMAIL_APP_KEY=<My email relays app key>
+zitadelctl writesecret zitadel.twilioauthtoken.existing --value $EMAIL_APP_KEY
+
+# Enjoy watching the zitadel pods becoming ready
+watch "kubectl --namespace caos-zitadel get pods"
+```
+
+ZITADEL needs [gRPC-Web](https://grpc.io/docs/platforms/web/basics/) for client-server communication, which the widely spread [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/) doesn't support out-of-the-box but Ambassador does. If you don't have an [Ambassador](https://www.getambassador.io/) running, we recommend you run it with our operator [BOOM](https://github.com/caos/orbos/blob/v4.0.0/docs/boom/boom.md).
+
+Download the template configuration file [boom.yml](./templates/boom.yml). Then adjust the values in boom.yml to match your environment.  
+
+```bash
+# Download the orbctl binary
+curl -s https://api.github.com/repos/caos/orbos/releases/latest | grep "browser_download_url.*orbctl.$(uname).$(uname -m)" | cut -d '"' -f 4 | sudo wget -i - -O /usr/local/bin/orbctl
+sudo chmod +x /usr/local/bin/orbctl
+sudo chown $(id -u):$(id -g) /usr/local/bin/orbctl
+
+# Deploy the operator to the current-context of your ~/.kube/config file
+orbctl takeoff
+
+# As soon as the configuration is applied, BOOM starts its work
+kubectl apply --filename ./boom.yml
+
+# Enjoy watching the ambassador pod becoming ready
+watch "kubectl --namespace caos-system get pods"
+```
+
+Congratulations, you can accept traffic at four new ZITADEL [subdomains](/docs/apis/domains) now.
--- a/docs/docs/guides/installation/gitops.md
+++ b/docs/docs/guides/installation/gitops.md
@@ -0,0 +1,55 @@
+---
+title: GitOps Mode on an existing Kubernetes cluster
+---
+
+:::tip What I need
+I'd like to have a reproducible ZITADEL environment and a pull-based configuration management for safe and comfortable day-two operations.
+:::
+
+First, copy the template files [database.yml](./templates/gitops/database.yml) and [zitadel.yml](./templates/gitops/zitadel.yml) to the root of a new git Repository. Then adjust the values in database.yml and zitadel.yml to match your environment. Especially the values for the domain, cluster DNS, storage class, email and Twilio are important.  
+
+Now open a terminal and execute the following commands.
+
+```bash
+# Download the zitadelctl binary
+curl -s https://api.github.com/repos/caos/zitadel/releases/latest | grep "browser_download_url.*zitadelctl-$(uname | awk '{print tolower($0)}')-amd64" | cut -d '"' -f 4 | sudo wget -i - -O /usr/local/bin/zitadelctl && sudo chmod +x /usr/local/bin/zitadelctl && sudo chown $(id -u):$(id -g) /usr/local/bin/zitadelctl
+sudo chmod +x /usr/local/bin/zitadelctl
+sudo chown $(id -u):$(id -g) /usr/local/bin/zitadelctl
+
+# Create an orb file at ${HOME}/.orb/config
+MY_GIT_REPO="git@github.com:me/my-orb.git"
+zitadelctl --gitops configure --repourl ${MY_GIT_REPO} --masterkey "$(openssl rand -base64 21)"
+
+# Write the Twiilio sender ID and auth token so that ZITADEL is able to send your users SMS.
+TWILIO_SID=<My Twilio Sender ID>
+TWILIO_AUTH_TOKEN=<My Twilio auth token>
+zitadelctl --gitops writesecret zitadel.twiliosid.encrypted --value $SID
+zitadelctl --gitops writesecret zitadel.twilioauthtoken.encrypted --value $TWILIO_AUTH_TOKEN
+
+# Write your email relays app key so that ZITADEL is able to verify your users email addresses
+EMAIL_APP_KEY=<My email relays app key>
+zitadelctl --gitops writesecret zitadel.twilioauthtoken.encrypted --value $EMAIL_APP_KEY
+
+# Deploy the operators to the current-context of your ~/.kube/config file
+zitadelctl --gitops takeoff
+
+# Enjoy watching the zitadel pods becoming ready
+watch "kubectl --namespace caos-zitadel get pods"
+```
+
+ZITADEL needs [gRPC-Web](https://grpc.io/docs/platforms/web/basics/) for client-server communication, which the widely spread [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/) doesn't support out-of-the-box but Ambassador does. If you don't have an [Ambassador](https://www.getambassador.io/) running, we recommend you run it with our operator [BOOM](https://github.com/caos/orbos/blob/v4.0.0/docs/boom/boom.md). Do so by adding the template [boom.yml](./templates/boom.yml) to the root of your Repository and execute the following commands. 
+
+```bash
+# Download the orbctl binary
+curl -s https://api.github.com/repos/caos/orbos/releases/latest | grep "browser_download_url.*orbctl.$(uname).$(uname -m)" | cut -d '"' -f 4 | sudo wget -i - -O /usr/local/bin/orbctl
+sudo chmod +x /usr/local/bin/orbctl
+sudo chown $(id -u):$(id -g) /usr/local/bin/orbctl
+
+# Deploy the operator to the current-context of your ~/.kube/config file
+orbctl --gitops takeoff
+
+# Enjoy watching the ambassador pod becoming ready
+watch "kubectl --namespace caos-system get pods"
+```
+
+Congratulations, you can accept traffic at four new ZITADEL [subdomains](/docs/apis/domains) now.
--- a/docs/docs/guides/installation/managed-dedicated-instance.md
+++ b/docs/docs/guides/installation/managed-dedicated-instance.md
@@ -0,0 +1,65 @@
+---
+title: Managed Dedicated Instance
+---
+
+:::tip What I need
+I'd like to simply use ZITADEL without having to take care of any operational tasks, yet keeping control over all its data.
+:::
+
+CAOS bootstraps and maintains a new ZITADEL instance just for you. This includes its underlying infrastructure with Kubernetes on top of it as well as monitoring tools and an API gateway. Contact us at <hi@zitadel.ch> for purchasing ZITADEL Enterprise Cloud.
+
+# Prerequisites
+
+Depending on the infrastructure provider you choose, you need to ensure some prerequisites.
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs
+  defaultValue="gce"
+  values={[
+    {label: 'Google Compute Engine', value: 'gce'},
+    {label: 'Cloudscale', value: 'cs'},
+    {label: 'Static Provider', value: 'static'},
+  ]}>
+  <TabItem value="gce">
+    <ul>
+        <li>
+            A JSON key for the infrastructure management to authenticate with a service account named orbiter-system assigned with the following roles
+            <ul>
+                <li>roles/compute.admin</li>
+                <li>roles/iap.tunnelResourceAccessor</li>
+                <li>roles/serviceusage.serviceUsageAdmin</li>
+                <li>roles/iam.serviceAccountUser</li>
+            </ul>
+        </li>
+        <li>
+            A JSON key for the backups storage to authenticate with a service account assigned with the role roles/storage.admin
+            <ul>
+                <li>roles/storage.admin</li>
+            </ul>
+        </li>
+    </ul>
+  </TabItem>
+  <TabItem value="cs">
+    <ul>
+        <li>A Cloudscale API token</li>        
+    </ul>
+  </TabItem>
+  <TabItem value="static">
+    <ul>
+        <li>A List of available CentOS 7 machines with their IP addresses</li>
+        <li>A passwordless sudo user called orbiter on all machines</li>
+        <li>A Bootstrap SSH key to login as orbiter (are replaced by ORBITER)</li>
+        <li>A storage solution (contact us)</li>
+    </ul>
+  </TabItem>
+</Tabs>
+
+- We need you to point [four DNS subdomains](/docs/apis/domains) to the CAOS-generated IP address.
+- For being able to send SMS, we need a Twilio sender name, SID and an auth token.
+- ZITADEL also needs to connect to an email relay of your choice. We need the SMTP host, user and app key as well as the ZITADEL emails sender address and name.
+
+If you give us a Cloudflare user, an API key and a user service key, we can also manage the DNS entries, wildcard certificate and the IP whitelisting automatically using the Cloudflare API.
+
+Metrics, logs and traces are collected and monitored by CAOS.
--- a/docs/docs/guides/installation/orbos.md
+++ b/docs/docs/guides/installation/orbos.md
@@ -0,0 +1,9 @@
+---
+title: GitOps Mode on dedicated Kubernetes Clusters using ORBOS
+---
+
+:::tip What I need
+I'd like to avoid platform failures caused by other applications or environments to have an impact on ZITADEL's production availability. So I run a near-identical dedicated GitOps managed Kubernetes cluster for each ZITADEL environment and region for proper isolation.
+:::
+
+> This will be added later on
--- a/docs/docs/guides/installation/shared-cloud.md
+++ b/docs/docs/guides/installation/shared-cloud.md
@@ -0,0 +1,11 @@
+---
+title: Shared Cloud at zitadel.ch
+---
+
+:::tip What I need
+I'd like to simply use ZITADEL without having to take care of any operational tasks.
+:::
+
+Just register your [Organization](../usage/organizations) at [zitadel.ch](https://console.zitadel.ch) and start by using [ZITADEL Free](https://zitadel.ch/pricing). You will immediately be able to integrate as many applications with as many users as you want. Serve your users multiple secure login methods for free.
+
+[Jump](../usage/get-started) to the more detailed docs.
--- a/docs/docs/guides/installation/templates/boom.yml
+++ b/docs/docs/guides/installation/templates/boom.yml
@@ -0,0 +1,37 @@
+apiVersion: caos.ch/v1
+kind: Boom
+metadata:
+  name: boom
+  namespace: caos-system
+spec:
+  boom:
+    version: v4.0.0
+  forceApply: true
+  currentStatePath: caos-internal/boom
+  apiGateway:
+    deploy: true
+    replicaCount: 1
+    proxyProtocol: true
+  metricCollection:
+    deploy: false
+  logCollection:
+    deploy: false
+  nodeMetricsExporter:
+    deploy: false
+  systemdMetricsExporter:
+    deploy: false
+  monitoring:
+    deploy: false
+  kubeMetricsExporter:
+    deploy: false
+  reconciling:
+    deploy: false
+  metricsPersisting:
+    deploy: false
+  logsPersisting:
+    deploy: false
+  metricsServer:
+    deploy: false
+  preApply:
+    deploy: false
+    folder: preapply
--- a/docs/docs/guides/installation/templates/crd/database.yml
+++ b/docs/docs/guides/installation/templates/crd/database.yml
@@ -0,0 +1,53 @@
+apiVersion: caos.ch/v1
+kind: Database
+metadata:
+  # This value must be database
+  name: database
+  # This value must be caos-system
+  namespace: caos-system
+spec:
+  kind: databases.caos.ch/Orb
+  version: v0
+  spec:
+    # Print debug logs
+    verbose: false
+    # This is the version of the database operator deployment
+    version: 1.0.0
+    # If true, the operator overwrites its own deployment using the version above
+    selfReconciling: true
+  database:
+    kind: databases.caos.ch/CockroachDB
+    version: v0
+    spec:
+      # Resources for the database pods
+      resources:
+        limits:
+          memory: 8Gi
+        requests:
+          cpu: 1
+          memory: 6Gi
+      # Print debug logs
+      verbose: false
+      # Number of database pods
+      replicaCount: 1
+      # PVC storage request
+      storageCapacity: 368Gi
+      # PVC storage class
+      storageClass: fast
+      # This value must match with your cluster DNS
+      clusterDNS: cluster.local
+      # If empty, the database isn't backuped
+      backups: {}
+    # bucket:
+    #   kind: databases.caos.ch/BucketBackup
+    #   version: v0
+    # spec:
+    #   # Print debug logs
+    #   verbose: true
+    #   # Schedule periodic backups
+    #   cron: 0 * * * *
+    #   # Specify the S3 bucket name
+    #   bucket: dummy
+    #   # The Google service accounts json key to use
+    #   # Use the zitadelctl writesecret command
+    #   serviceAccountJSON: {}
--- a/docs/docs/guides/installation/templates/crd/zitadel.yml
+++ b/docs/docs/guides/installation/templates/crd/zitadel.yml
@@ -0,0 +1,74 @@
+apiVersion: caos.ch/v1
+kind: Zitadel
+metadata:
+  # This value must be zitadel
+  name: zitadel
+  # This value must be caos-system
+  namespace: caos-system
+spec:
+  kind: zitadel.caos.ch/Orb
+  version: v0
+  spec:
+    # Print debug logs
+    verbose: false
+    # This is the version of the ZITADEL operator deployment and the ZITADEL binary deployment
+    version: 1.0.0
+    # If true, the operator overwrites its own deployment using the version above
+    selfReconciling: true
+  iam:
+    kind: zitadel.caos.ch/ZITADEL
+    version: v0
+    spec:
+      # Print debug logs
+      verbose: false
+      # If true, Kubernetes resources are applied forcefully
+      force: false
+      # Number of ZITADEL pods
+      replicaCount: 1
+      # ZITADEL deployment configuration
+      configuration:
+        cache:
+          maxAge: 12h
+          sharedMaxAge: 168h
+          shortMaxAge: 5m
+          shortSharedMaxAge: 15m
+        # Keys ZITADEL uses for symmetric encryption
+        secrets:
+          existingKeys:
+            key: keys
+            name: zitadel
+          userVerificationID: userverificationkey_1
+          otpVerificationID: otpverificationkey_1
+          oidcKeysID: oidckey_1
+          cookieID: cookiekey_1
+          csrfID: cookiekey_1
+          domainVerificationID: domainverificationkey_1
+          idpConfigVerificationID: idpconfigverificationkey_1
+        notifications:
+          # Email configuration is used for sending verification emails
+          email:
+            smtpHost: smtp.gmail.com:465
+            smtpUser: dummy
+            senderAddress: dummy
+            senderName: dummy
+            tls: true
+          # Twilio configuration is used for sending second factor SMS
+          twilio:
+            senderName: dummy
+        # If true, no emails or SMS are sent to users
+        debugMode: true
+        # ZITADEL pods log level
+        logLevel: info
+        dns:
+          # The main domain, the ZITADEL APIs should be published at
+          domain: myzitadel.ch
+          # The tls wildcard certificate used for publishing the zitadel endpoints over HTTPS
+          tlsSecret: tls-cert-wildcard
+          # The subdomains, the ZITADEL APIs should be published at
+          subdomains:
+            accounts: accounts
+            api: api
+            console: console
+            issuer: issuer
+        # This value must match with your cluster DNS
+        clusterdns: cluster.local
--- a/docs/docs/guides/installation/templates/example_keys
+++ b/docs/docs/guides/installation/templates/example_keys
@@ -0,0 +1,6 @@
+otpverificationkey_1: passphrasewhichneedstobe32bytes!
+cookiekey_1: passphrasewhichneedstobe32bytes!
+domainverificationkey_1: passphrasewhichneedstobe32bytes!
+idpconfigverificationkey_1: passphrasewhichneedstobe32bytes!
+oidckey_1: passphrasewhichneedstobe32bytes!
+userverificationkey_1: passphrasewhichneedstobe32bytes!
--- a/docs/docs/guides/installation/templates/gitops/database.yml
+++ b/docs/docs/guides/installation/templates/gitops/database.yml
@@ -0,0 +1,45 @@
+kind: databases.caos.ch/Orb
+version: v0
+spec:
+  # Print debug logs
+  verbose: false
+  # This is the version of the database operator deployment
+  version: 1.0.0
+  # If true, the operator overwrites its own deployment using the version above
+  selfReconciling: true
+database:
+  kind: databases.caos.ch/CockroachDB
+  version: v0
+  spec:
+    # Resources for the database pods
+    resources:
+      limits:
+        memory: 8Gi
+      requests:
+        cpu: 1
+        memory: 6Gi
+    # Print debug logs
+    verbose: false
+    # Number of database pods
+    replicaCount: 1
+    # PVC storage request
+    storageCapacity: 368Gi
+    # PVC storage class
+    storageClass: fast
+    # This value must match with your cluster DNS
+    clusterDNS: cluster.local
+      # If empty, the database isn't backuped
+    backups: {}
+  # bucket:
+  #   kind: databases.caos.ch/BucketBackup
+  #   version: v0
+  # spec:
+  #   # Print debug logs
+  #   verbose: true
+  #   # Schedule periodic backups
+  #   cron: 0 * * * *
+  #   # Specify the S3 bucket name
+  #   bucket: dummy
+  #   # The Google service accounts json key to use
+  #   # Use the zitadelctl writesecret command
+  #   serviceAccountJSON: {}
--- a/docs/docs/guides/installation/templates/gitops/zitadel.yml
+++ b/docs/docs/guides/installation/templates/gitops/zitadel.yml
@@ -0,0 +1,54 @@
+kind: zitadel.caos.ch/Orb
+version: v0
+spec:
+  # Print debug logs
+  verbose: false
+  # This is the version of the ZITADEL operator deployment and the ZITADEL binary deployment
+  version: 1.0.0
+  # If true, the operator overwrites its own deployment using the version above
+  selfReconciling: true
+iam:
+  kind: zitadel.caos.ch/ZITADEL
+  version: v0
+  spec:
+    # Print debug logs
+    verbose: false
+    # If true, Kubernetes resources are applied forcefully
+    force: false
+    # Number of zitadel pods
+    replicaCount: 1
+    # ZITADEL deployment configuration
+    configuration:
+      cache:
+        maxAge: 12h
+        sharedMaxAge: 168h
+        shortMaxAge: 5m
+        shortSharedMaxAge: 15m
+      notifications:
+        # Email configuration is used for sending verification emails
+        email:
+          smtpHost: smtp.gmail.com:465
+          smtpUser: dummy
+          senderAddress: dummy
+          senderName: dummy
+          tls: true
+        # Twilio configuration is used for sending second factor SMS
+        twilio:
+          senderName: dummy
+      # If true, no emails or SMS are sent to users
+      debugMode: true
+      # ZITADEL pods log level
+      logLevel: info
+      dns:
+        # The main domain, the ZITADEL APIs should be published at
+        domain: myzitadel.ch
+        # The tls wildcard certificate used for publishing the zitadel endpoints over HTTPS
+        tlsSecret: tls-cert-wildcard
+        # The subdomains, the ZITADEL APIs should be published at
+        subdomains:
+          accounts: accounts
+          api: api
+          console: console
+          issuer: issuer
+      # This value must match with your cluster DNS
+      clusterdns: cluster.local