|
| 1 | ++++ |
| 2 | +title = "Quickstart" |
| 3 | +weight = 1 |
| 4 | ++++ |
| 5 | + |
| 6 | +This quickstart provides the steps to install the Kubermatic Developer Platform (KDP) on an existing Kubernetes cluster. |
| 7 | +You'll use Helm to deploy KDP and its core components, including Dex for user authentication and kcp as central control plane. |
| 8 | +You will also set up automated TLS certificate management with cert-manager and Let's Encrypt. |
| 9 | +By the end, you will have a fully functional KDP installation, accessible through the KDP dashboard as well as directly with kubectl. |
| 10 | + |
| 11 | +## Prerequisites |
| 12 | + |
| 13 | +{{% notice note %}} |
| 14 | +At the moment, you need to be invited to get access to Kubermatic's Docker repository before you can install the Kubermatic Developer Platform. |
| 15 | +Please [contact sales](mailto:sales@kubermatic.com) to receive your credentials. |
| 16 | +{{% /notice %}} |
| 17 | + |
| 18 | +To follow this guide, you need: |
| 19 | + |
| 20 | +* an existing Kubernetes cluster with at least 3 nodes |
| 21 | +* a running CSI driver with a default storage class |
| 22 | +* a running [cert-manager][cert-manager/docs/installation] installation |
| 23 | +* an running ingress controller (for this guide, the [NGINX ingress controller][ingress-nginx/docs/installation] is required) |
| 24 | +* [kubectl][k8s/docs/tools/installation] and [Helm][helm/docs/installation] (version 3) installed locally |
| 25 | + |
| 26 | +## Installation |
| 27 | + |
| 28 | +The installation is divided into five main steps, each deploying a core component of KDP. |
| 29 | +You will perform the following tasks: |
| 30 | + |
| 31 | +* **Set up certificates**: First, you will configure a cert-manager issuer to automatically obtain and renew TLS certificates from Let's Encrypt. |
| 32 | + |
| 33 | +* **Deploy an identity provider**: Next, you will deploy Dex to handle user authentication, creating a central login service for both the KDP dashboard and command-line access. |
| 34 | + |
| 35 | +* **Deploy kcp**: You will deploy kcp, the core engine that enables multi-tenancy by providing isolated, secure workspaces for your users. |
| 36 | + |
| 37 | +* **Deploy KDP**: Afterwards, you will install the main KDP controllers that connect to kcp and manage the platform's resources. |
| 38 | + |
| 39 | +* **Launch the KDP dashboard**: Finally, you will deploy the KDP dashboard, the primary graphical interface for developers to interact with the platform and manage their service objects. |
| 40 | + |
| 41 | +Throughout this guide, you will need to replace several placeholder variables in the Helm values files. |
| 42 | +Below is a description of each value you need to provide. |
| 43 | + |
| 44 | +* `<EMAIL_ADDRESS>`: Your email address, used by Let's Encrypt to send notifications about your TLS certificate status. |
| 45 | +* `<PULL_CREDENTIALS>`: A base64-encoded password or token for the quay.io container registry. This is required for you to get access to the KDP Helm charts and container images. |
| 46 | +* `<DOMAIN>`: The primary public domain name you will use to access your KDP installation (e.g., kdp.my-company.com). You must own this domain and be able to configure its DNS records. |
| 47 | +* `<ADMIN_PASSWORD_HASH>`: A generated bcrypt hash of the password you choose for the initial admin user. |
| 48 | +* `<OIDC_CLIENT_SECRET>`: A randomly generated, secure string that acts as a password for the KDP dashboard to authenticate with the Dex identity provider. |
| 49 | +* `<SESSION_ENCRYPTION_KEY>`: A second, unique random string used by the KDP dashboard itself to encrypt user session cookies, adding another layer of security. |
| 50 | + |
| 51 | +### Create ClusterIssuer |
| 52 | + |
| 53 | +First, you need to create a _ClusterIssuer_ named `letsencrypt-prod` for cert-manager. |
| 54 | +This automates the process of obtaining and renewing TLS certificates from Let's Encrypt, ensuring all web-facing components like the Dex login page and the KDP dashboard are served securely over HTTPS. |
| 55 | + |
| 56 | +Save the following content to a file named `cluster-issuer.yaml`, and change the value of the `email` field to your email address: |
| 57 | + |
| 58 | +```yaml |
| 59 | +{{< readfile "developer-platform/setup/quickstart/data/letsencrypt.cluster-issuer.yaml" >}} |
| 60 | +``` |
| 61 | + |
| 62 | +Create the _ClusterIssuer_ by applying the manifest: |
| 63 | + |
| 64 | +```bash |
| 65 | +$ kubectl apply -f ./cluster-issuer.yaml |
| 66 | +``` |
| 67 | + |
| 68 | +### Deploy Dex |
| 69 | + |
| 70 | +Now, you'll deploy Dex as the platform's central identity provider. |
| 71 | +It handles all user logins and authentication. |
| 72 | +The provided configuration creates an initial admin user and prepares Dex for the integration with the KDP dashboard and [kubelogin][kubelogin/src/readme] for a seamless user authentication. |
| 73 | + |
| 74 | +Save the following content to a file named `dex.values.yaml`: |
| 75 | + |
| 76 | +```yaml |
| 77 | +{{< readfile "developer-platform/setup/quickstart/data/dex.values.yaml" >}} |
| 78 | +``` |
| 79 | + |
| 80 | +Before deploying Dex, you need to replace the following placeholder variables in the `dex.values.yaml` file with your own values: |
| 81 | + |
| 82 | +* `<DOMAIN>` |
| 83 | +* `<ADMIN_PASSWORD_HASH>` |
| 84 | +* `<OIDC_CLIENT_SECRET>` |
| 85 | + |
| 86 | +For the initial admin user, you must provide your own password as bcrypt hash in `<ADMIN_PASSWORD_HASH>`. |
| 87 | +To create this hash, you can use the `htpasswd` utility, which is part of the Apache web server tools and available on most Linux distributions (you may need to install a package like "apache2-utils" or "httpd-tools"). |
| 88 | + |
| 89 | +Choose a strong password and run the following command in your terminal, replacing YOUR_PASSWORD with the password you've selected: |
| 90 | + |
| 91 | +```bash |
| 92 | +$ echo 'YOUR_PASSWORD' | htpasswd -inBC 10 admin | cut -d: -f2 |
| 93 | +``` |
| 94 | + |
| 95 | +Copy the entire output string (it will start with `$2a$` or `$2y$`) and paste it as the value for `<ADMIN_PASSWORD_HASH>` in your `dex.values.yaml` file. |
| 96 | +Remember to save the plain-text password you chose in a secure location, as you will need it to log in to the KDP dashboard. |
| 97 | + |
| 98 | +The `<OIDC_CLIENT_SECRET>` placeholder must be replaced with a long, random string that the KDP dashboard and kubelogin use to securely communicate with Dex. |
| 99 | +You can generate a secure, random string with the following command: |
| 100 | + |
| 101 | +```bash |
| 102 | +$ cat /dev/urandom | base64 | tr -dc 'A-Za-z0-9' | head -c32 |
| 103 | +``` |
| 104 | + |
| 105 | +This will output a random string that you can copy and paste as the value for `<OIDC_CLIENT_SECRET>`. |
| 106 | +Save the value for later use when you deploy the KDP dashboard. |
| 107 | + |
| 108 | +Once you've replaced all placeholders, deploy the Dex Helm chart: |
| 109 | + |
| 110 | +```bash |
| 111 | +$ helm upgrade --install dex dex \ |
| 112 | + --repo=https://charts.dexidp.io \ |
| 113 | + --version=0.23.0 \ |
| 114 | + --create-namespace \ |
| 115 | + --namespace=kdp-system \ |
| 116 | + --values=dex.values.yaml |
| 117 | +``` |
| 118 | + |
| 119 | +### Deploy kcp |
| 120 | + |
| 121 | +Next, you'll install kcp. |
| 122 | +It acts as the central control plane for KDP that provides and manages the isolated workspaces for each user or team, ensuring resources are kept separate and secure. |
| 123 | +It's configured to use Dex for authenticating user requests. |
| 124 | + |
| 125 | +Save the following content to a file named `kcp.values.yaml`: |
| 126 | + |
| 127 | +```yaml |
| 128 | +{{< readfile "developer-platform/setup/quickstart/data/kcp.values.yaml" >}} |
| 129 | +``` |
| 130 | + |
| 131 | +Before deploying kcp, you need to replace the following placeholder variables in the `kcp.values.yaml` file with your own values: |
| 132 | + |
| 133 | +* `<DOMAIN>` |
| 134 | + |
| 135 | +After you've replaced all the placeholders, deploy the kcp Helm chart: |
| 136 | + |
| 137 | +```bash |
| 138 | +$ helm upgrade --install kcp kcp \ |
| 139 | + --repo=https://kcp-dev.github.io/helm-charts \ |
| 140 | + --version=0.11.1 \ |
| 141 | + --create-namespace \ |
| 142 | + --namespace=kdp-system \ |
| 143 | + --values=kcp.values.yaml |
| 144 | +``` |
| 145 | + |
| 146 | +### Deploy KDP |
| 147 | + |
| 148 | +Finally, you'll deploy the main KDP application. |
| 149 | +It connects to the kcp control plane and includes a one-time bootstrap job that grants the admin user full administrative rights, allowing them to manage the entire platform. |
| 150 | + |
| 151 | +Save the following content to a file named `kdp.values.yaml`: |
| 152 | + |
| 153 | +```yaml |
| 154 | +{{< readfile "developer-platform/setup/quickstart/data/kdp.values.yaml" >}} |
| 155 | +``` |
| 156 | + |
| 157 | +Before deploying KDP, you need to replace the following placeholder variables in the `kdp.values.yaml` file with your own values: |
| 158 | + |
| 159 | +* `<PULL_CREDENTIALS>` |
| 160 | +* `<DOMAIN>` |
| 161 | + |
| 162 | +With all placeholders replaced, deploy the KDP Helm chart. |
| 163 | +Use your email address as the username and the license key you received as the password to log into the Helm registry. |
| 164 | + |
| 165 | +```bash |
| 166 | +$ helm registry login quay.io |
| 167 | +$ helm upgrade --install kdp \ |
| 168 | + oci://quay.io/kubermatic/helm-charts/developer-platform \ |
| 169 | + --version=0.9.0 \ |
| 170 | + --create-namespace \ |
| 171 | + --namespace=kdp-system \ |
| 172 | + --values=kdp.values.yaml |
| 173 | +``` |
| 174 | + |
| 175 | +### Deploy KDP dashboard |
| 176 | + |
| 177 | +Last but not least, you'll deploy the KDP's web-based dashboard, which serves as the primary user interface. |
| 178 | +It's configured to use Dex for user login and connects to kcp, providing developers with a graphical interface to create and manage their service objects. |
| 179 | + |
| 180 | +Save the following content to a file named `kdp-dashboard.values.yaml`: |
| 181 | + |
| 182 | +```yaml |
| 183 | +{{< readfile "developer-platform/setup/quickstart/data/kdp-dashboard.values.yaml" >}} |
| 184 | +``` |
| 185 | + |
| 186 | +Before deploying the KDP dashboard, you need to replace the following placeholder variables in the `kdp-dashboard.values.yaml` file with your own values: |
| 187 | + |
| 188 | +* `<PULL_CREDENTIALS>` |
| 189 | +* `<DOMAIN>` |
| 190 | +* `<OIDC_CLIENT_SECRET>` |
| 191 | +* `<SESSION_ENCRYPTION_KEY>` |
| 192 | + |
| 193 | +The `<OIDC_CLIENT_SECRET>` placeholder **must** be replaced with the value generated in step "Deploy Dex" and configured in the `dex.values.yaml` file. |
| 194 | + |
| 195 | +The `<SESSION_ENCRYPTION_KEY>` placeholder must - similar to the OIDC client secret - be replaced with a long, random string that the KDP dashboard uses to protect user sessions. |
| 196 | +You can use the same command, to generate a secure, random string: |
| 197 | + |
| 198 | +```bash |
| 199 | +$ cat /dev/urandom | base64 | tr -dc 'A-Za-z0-9' | head -c32 |
| 200 | +``` |
| 201 | + |
| 202 | +Copy and paste the output as the value for `<SESSION_ENCRYPTION_KEY>`. |
| 203 | + |
| 204 | +Now that all placeholders are replaced, deploy the KDP dashboard Helm chart. |
| 205 | +To log into the Helm registry, again use your email address as the username and the license key you received as the password. |
| 206 | + |
| 207 | +```bash |
| 208 | +$ helm registry login quay.io |
| 209 | +$ helm upgrade --install kdp-dashboard \ |
| 210 | + oci://quay.io/kubermatic/helm-charts/developer-platform-dashboard \ |
| 211 | + --version=0.9.0 \ |
| 212 | + --create-namespace \ |
| 213 | + --namespace=kdp-system \ |
| 214 | + --values=kdp-dashboard.values.yaml |
| 215 | +``` |
| 216 | + |
| 217 | +### Configure DNS records |
| 218 | + |
| 219 | +In order to finalize the installation and make your KDP instance accessible, you must create four records in your DNS provider. |
| 220 | +These records point the hostnames you configured earlier to the correct load balancers of your Kubernetes cluster. |
| 221 | + |
| 222 | +First, create three DNS records that direct traffic for the Dex login page (`login.<DOMAIN>`), the public API endpoint (`api.<DOMAIN>`), and the KDP dashboard (`dashboard.<DOMAIN>`) to your cluster's NGINX ingress controller. |
| 223 | + |
| 224 | +Assuming you installed the NGINX ingress controller into the `ingress-nginx` namespace, use the following command to the retrieve the external IP address or DNS name of the load balancer (in column "EXTERNAL-IP"): |
| 225 | + |
| 226 | +```bash |
| 227 | +$ kubectl --namespace=ingress-nginx get service ingress-nginx-controller |
| 228 | +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE |
| 229 | +ingress-nginx-controller LoadBalancer 10.47.248.232 4cdd93dfab834ed9a78858c7f2633380.eu-west-1.elb.amazonaws.com 80:30807/TCP,443:30184/TCP 449d |
| 230 | +``` |
| 231 | +Second, create a DNS record specifically for kcp (`internal.<DOMAIN>`) that points to the external IP address or DNS name of the dedicated load balancer for the kcp _Service_. |
| 232 | +Use the following command to the retrieve the external IP address or DNS name of kcp's load balancer: |
| 233 | + |
| 234 | +```bash |
| 235 | +$ kubectl --namespace=kdp-system get service kcp-front-proxy |
| 236 | +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE |
| 237 | +kcp-front-proxy LoadBalancer 10.240.20.65 99f1093e45d6482d95a0c22c4a2bd056.eu-west-1.elb.amazonaws.com 8443:30295/TCP 381d |
| 238 | +``` |
| 239 | + |
| 240 | +### Access the dashboard |
| 241 | + |
| 242 | +Congratulations, your KDP installation is now complete! Once your DNS records have propagated, you can access the dashboard by navigating your web browser to the URL you configured (`https://dashboard.<DOMAIN>`). |
| 243 | + |
| 244 | +You will be redirected to the Dex login page and you can use the administrative credentials that were created during the setup: |
| 245 | + |
| 246 | +* **Username**: `admin` |
| 247 | +* **Password**: The password you chose in step [Deploy Dex](#deploy-dex) |
| 248 | + |
| 249 | +After logging in, you will be taken to the KDP dashboard, where you can begin exploring your platform. Welcome to KDP! |
| 250 | + |
| 251 | +[cert-manager/docs/installation]: https://cert-manager.io/docs/installation/helm/ |
| 252 | +[helm/docs/installation]: https://helm.sh/docs/intro/install/ |
| 253 | +[ingress-nginx/docs/installation]: https://kubernetes.github.io/ingress-nginx/deploy/ |
| 254 | +[k8s/docs/tools/installation]: https://kubernetes.io/docs/tasks/tools/#kubectl |
| 255 | +[kcp/chart/readme]: https://github.com/kcp-dev/helm-charts/tree/main/charts/kcp |
| 256 | +[kubelogin/src/readme]: https://github.com/int128/kubelogin |
0 commit comments