From 616f064e9978300ba55bc4710f72e64bd4380882 Mon Sep 17 00:00:00 2001 From: Elio Bischof Date: Thu, 25 May 2023 10:21:35 +0200 Subject: [PATCH] docs: improve installation guide for k8s (#5923) * docs(k8s): add port-forward command * docs: improve k8s installation docs * remove target port --------- Co-authored-by: Fabi --- docs/docs/self-hosting/deploy/kubernetes.mdx | 45 +++++++++++--------- 1 file changed, 26 insertions(+), 19 deletions(-) diff --git a/docs/docs/self-hosting/deploy/kubernetes.mdx b/docs/docs/self-hosting/deploy/kubernetes.mdx index 7d3385666..fa214d577 100644 --- a/docs/docs/self-hosting/deploy/kubernetes.mdx +++ b/docs/docs/self-hosting/deploy/kubernetes.mdx @@ -10,49 +10,61 @@ Installation and configuration details are described in the [open source ZITADEL By default, the chart installs a secure and highly available ZITADEL instance. For running an easily testable, insecure, non-HA ZITADEL instance, run the following commands. -## Helm -### Add the helm repositories for CockroachDB and ZITADEL +## Add the Helm Repositories for CockroachDB and ZITADEL ```bash helm repo add cockroachdb https://charts.cockroachdb.com/ helm repo add zitadel https://charts.zitadel.com ``` -### Install zitadel +After you have your repositories added, +you can setup ZITADEL and either +- initialize an [IAM owner who is a human user](#setup-zitadel-and-a-human-admin) or +- initialize an [IAM owner who is a service account](#setup-zitadel-and-a-service-account-admin) -#### Install an insecure cockroachdb and zitadel release that works with localhost +## Setup ZITADEL and a Human Admin ```bash -# CockroachDB +# Install CockroachDB helm install crdb cockroachdb/cockroachdb \ --set fullnameOverride=crdb \ --set single-node=true \ --set statefulset.replicas=1 -# ZITADEL +# Install ZITADEL helm install my-zitadel zitadel/zitadel \ --set zitadel.masterkey="MasterkeyNeedsToHave32Characters" \ --set zitadel.configmapConfig.ExternalSecure=false \ --set zitadel.configmapConfig.TLS.Enabled=false \ --set zitadel.secretConfig.Database.cockroach.User.Password="a-zitadel-db-user-password" \ --set replicaCount=1 + +# Make ZITADEL locally accessible +kubectl port-forward svc/my-zitadel 8080 ``` -#### Install an insecure zitadel release that works with localhost with a service account +## Setup ZITADEL and a Service Account Admin -!!!Caution!!! With this setup you only get a service account with a key and no admin account where you can login directly into ZITADEL. +With this setup, you don't create a human user that has the IAM_OWNER role. +Instead, you create a service account that has the IAM_OWNER role. +ZITADEL will also create a key for your, with which you can authenticate to the ZITADEL API. +For example, you can install ZITADEL and seemlessly provision ZITADEL resources after installation using [Terraform](/docs/guides/manage/terraform/basics.md). + +:::caution +With this setup you only get a key for a service account. Logging in at ZITADEL using the login screen is not possible until you create a user with the ZITADEL API. +::: ```bash -# CockroachDB +# Install CockroachDB helm install crdb cockroachdb/cockroachdb \ --set fullnameOverride=crdb \ --set single-node=true \ --set statefulset.replicas=1 -# ZITADEL +# Install ZITADEL helm install --namespace zitadel --create-namespace my-zitadel zitadel/zitadel \ --set zitadel.masterkey="MasterkeyNeedsToHave32Characters" \ --set zitadel.configmapConfig.ExternalSecure=false \ @@ -63,20 +75,15 @@ helm install --namespace zitadel --create-namespace my-zitadel zitadel/zitadel \ --set zitadel.configmapConfig.FirstInstance.Org.Machine.Machine.Username="zitadel-admin-sa" \ --set zitadel.configmapConfig.FirstInstance.Org.Machine.Machine.Name="Admin" \ --set zitadel.configmapConfig.FirstInstance.Org.Machine.MachineKey.Type=1 + +# Make ZITADEL locally accessible +kubectl port-forward svc/my-zitadel 8080 ``` -When helm is done, you get a command to retrieve your machine key, which is saved as a kubernetes secret, for example: +When Helm is done, you can print your service account key from a Kubernetes secret: ```bash kubectl -n zitadel get secret zitadel-admin-sa -o jsonpath='{ .data.zitadel-admin-sa\.json }' | base64 -D ``` -This key can be used to provision resources with for example [Terraform](/docs/guides/manage/terraform/basics.md). - -### Forward the ZITADEL service port to your local machine - -```bash -kubectl port-forward svc/my-zitadel 8080:8080 -``` -