From a5433e0b308a965d37e861ad451bcbc8e6cce707 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Justinas=20Stankevi=C4=8Dius?= Date: Wed, 21 Feb 2024 16:28:17 +0200 Subject: [PATCH] [v14] Add a guide for deploying TAG using Helm (#38266) (#38403) * Update TAG version to 1.11.0 * Add a guide for deploying TAG using Helm * Fix prose lint * Add auto-generated reference for TAG Helm chart * Apply suggestions from code review * Update TAG example role to v7 * Fix link to TAG Helm guide * Pin TAG Helm chart version Pins to the same version as TAG itself, Helm chart and TAG are versioned in lockstep * Call out the teleport Helm chart more explicitly * Bump TAG version to 1.13.0 Expecting it to be released by the time these docs go live. * Replace teleport-cluster parameters with Vars * Elaborate trust of the TAG CA in Teleport * Fix the marker style * Fix the link to teleport-cluster reference --------- Co-authored-by: Paul Gottschling --- docs/config.json | 16 +- .../access-graph/self-hosted-helm.mdx | 229 ++++++++++++++++++ .../access-graph/self-hosted.mdx | 10 +- docs/pages/reference/helm-reference.mdx | 2 + .../zz_generated.teleport-access-graph.mdx | 152 ++++++++++++ .../helm-reference/teleport-access-graph.mdx | 19 ++ 6 files changed, 422 insertions(+), 6 deletions(-) create mode 100644 docs/pages/access-controls/access-graph/self-hosted-helm.mdx create mode 100644 docs/pages/reference/helm-reference/includes/zz_generated.teleport-access-graph.mdx create mode 100644 docs/pages/reference/helm-reference/teleport-access-graph.mdx diff --git a/docs/config.json b/docs/config.json index a7dfe3a3b4740..26b815cb239a0 100644 --- a/docs/config.json +++ b/docs/config.json @@ -653,6 +653,13 @@ "forScopes": [ "enterprise" ] + }, + { + "title": "TAG for Self-Hosted Clusters with Helm", + "slug": "/access-controls/access-graph/self-hosted-helm/", + "forScopes": [ + "enterprise" + ] } ] }, @@ -1952,6 +1959,13 @@ "title": "teleport-kube-agent", "slug": "/reference/helm-reference/teleport-kube-agent/" }, + { + "title": "teleport-access-graph", + "slug": "/reference/helm-reference/teleport-access-graph/", + "forScopes": [ + "enterprise" + ] + }, { "title": "teleport-plugin-event-handler", "slug": "/reference/helm-reference/teleport-plugin-event-handler/" @@ -2069,7 +2083,7 @@ "nodeIP": "ip-172-31-35-170" }, "access_graph": { - "version": "1.9.1" + "version": "1.13.0" }, "ansible": { "min_version": "2.9.6" diff --git a/docs/pages/access-controls/access-graph/self-hosted-helm.mdx b/docs/pages/access-controls/access-graph/self-hosted-helm.mdx new file mode 100644 index 0000000000000..011725057ddda --- /dev/null +++ b/docs/pages/access-controls/access-graph/self-hosted-helm.mdx @@ -0,0 +1,229 @@ +--- +title: Run Teleport Access Graph on Self-Hosted Clusters with Helm +--- + +Using Access Graph with a self-hosted Teleport cluster requires +setting up the Teleport Access Graph (TAG) service. +TAG is a dedicated service which uses PostgreSQL as its backing storage +and communicates with Auth Service and Proxy Service +to collect information about resources and access. + +This guide will help you set up the TAG service +in a Kubernetes cluster using a Helm Chart, +and enable the Access Graph feature in your Teleport cluster. + +The full listing of supported parameters can be found in the [`teleport-access-graph` Helm chart reference](../../reference/helm-reference/teleport-access-graph.mdx). + +Teleport Access Graph is enabled by default for Teleport Team users. +You can skip the setup process and start using Access Graph right away +by signing up for a [Teleport Team trial](https://goteleport.com/signup/). + +## Prerequisites + +- Kubernetes >= v1.21 +- Helm >= (=helm.version=) +- A running Teleport Enterprise cluster v14.3.4 or later. + - For the purposes of this guide, we assume that the Teleport cluster is set up + [using the `teleport-cluster` Helm chart](../../deploy-a-cluster/helm-deployments.mdx) + in the same Kubernetes cluster that will be used to deploy Teleport Access Graph . +- An updated `license.pem` with Teleport Policy enabled. +- A PostgreSQL database server v14 or later. + - Access Graph needs a dedicated [database](https://www.postgresql.org/docs/current/sql-createdatabase.html) to store its data. + The user that TAG connects to the database with needs to be the owner of this database, or have similar broad permissions: + at least the `CREATE TABLE` privilege on the `public` schema, and the `CREATE SCHEMA` privilege. + - Amazon RDS for PostgreSQL is supported. +- A TLS certificate for the Access Graph service + - The TLS certificate must be issued for "server authentication" key usage, + and must contain a X.509 v3 `subjectAltName` extension with the Kubernetes service name for TAG + (`teleport-access-graph.teleport-access-graph.svc.cluster.local` by default). + + +## Step 1/4. Add the Teleport Helm chart repository + +(!docs/pages/kubernetes-access/helm/includes/helm-repo-add.mdx!) + +## Step 2/4. Set up the Teleport Access Graph service + +You will need a copy of your Teleport cluster's host certificate authority (CA). +TAG requires incoming connections to be authenticated via host certificates that the host CA issues to the Auth Service and Proxy Service. + +The host CA can be retrieved in one of the following ways: + + + +```code +$ curl 'https:///webapi/auth/export?type=tls-host' +-----BEGIN CERTIFICATE----- +MIIDqjCCApKgAwIBAgIQMIK8/WiQ/rUOrjlmB0IHVTANBgkqhkiG9w0BAQsFADBv +<...> +-----END CERTIFICATE----- +``` + + + +```code +$ tsh login --proxy= +$ tctl get cert_authorities --format=json \ + | jq -r '.[] | select(.spec.type == "host") | .spec.active_keys.tls[].cert' \ + | base64 -d +-----BEGIN CERTIFICATE----- +MIIDqjCCApKgAwIBAgIQMIK8/WiQ/rUOrjlmB0IHVTANBgkqhkiG9w0BAQsFADBv +<...> +-----END CERTIFICATE----- +``` + + + +Then, create the namespace and required secrets for the TAG deployment. +You can skip the final command if you are instead using cert-manager to issue the certificate, +or otherwise have already provisioned the TLS certificate for Teleport Access Graph in your Kubernetes cluster. + +```code +$ kubectl create namespace teleport-access-graph +$ kubectl -n teleport-access-graph create secret generic teleport-access-graph-postgres \ + --from-literal uri="postgres://access_graph_user:my_password@db.example.com:5432/access_graph_db?sslmode=require" +$ kubectl -n teleport-access-graph create secret tls teleport-access-graph-tls --cert=./certs/cert.crt --key=./certs/cert.key +``` + +The above commands assume that you have the TLS certificate and private key for the TAG server stored under the `./certs` directory. + +
+The following script can be used to quickly generate a certificate authority and server TLS certificate for deploying TAG. + +```sh +#!/usr/bin/env bash + +set -e + +mkdir -p ./certs +cd ./certs + +openssl genrsa -aes256 -out ca.key 4096 +openssl req -x509 -new -key ca.key -sha256 -days 3652 -out ca.crt -subj '/CN=root' +openssl req -new -out cert.csr -newkey rsa:4096 -nodes -keyout cert.key -subj '/CN=Access Graph' +openssl x509 -req -in cert.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out cert.crt -days 3652 -sha256 \ + -extfile <(printf 'extendedKeyUsage = serverAuth, clientAuth\nsubjectAltName = DNS:teleport-access-graph.teleport-access-graph.svc.cluster.local') + +echo "Certificates issued successfully" +``` + +The script will ask to input the same password 4 times: +twice to create and confirm the password to encrypt the CA private key material with, +then once to use the private key to self-sign the CA certificate, +and finally once to use for signing the TAG server certificate. + +Please note that this script is only provided for proof-of-concept deployments, +and may not follow the best security practices. +
+ +After provisioning the secrets, create the following file named `tag-values.yaml` file for the TAG deployment, +replacing the value under the `clusterHostCAs` key with the Teleport Host CA certificate retrieved previously. + +```yaml +postgres: + secretName: "teleport-access-graph-postgres" + +tls: + # You may need to change this value if using cert-manager or other means + # to provision TLS certificates for your Kubernetes workloads. + existingSecretName: "teleport-access-graph-tls" + +clusterHostCAs: + # Replace this with the certificate retrieved in Step 1. + # `clusterHostCAs` is an array of multiline YAML strings, `- |` must not be removed, and the indentation must be kept. + - | + -----BEGIN CERTIFICATE----- + MIIDqjCCApKgAwIBAgIQMIK8/WiQ/rUOrjlmB0IHVTANBgkqhkiG9w0BAQsFADBv + <...> + -----END CERTIFICATE----- +``` + +Finally, deploy the TAG service using Helm: + +```code +$ helm install -n teleport-access-graph -f tag-values.yaml --version (=access_graph.version=) teleport-access-graph teleport/teleport-access-graph +$ kubectl -n teleport-access-graph rollout status deployment/teleport-access-graph # Wait for the deployment to succeed +``` + +## Step 3/4. Update the Teleport Auth Service configuration + +To enable connectivity between the Teleport Auth Service and the Teleport Access Graph Service, +the Auth Service configuration needs to be updated with: +- The TAG service address +- The path to the CA which issued the TAG service TLS certificate. + - This path must refer to a volume containing the CA, mounted on the Teleport pods. + - Specifying the CA certificate file can be skipped if you are using a CA that is already trusted by the Teleport cluster + (e.g. via the [`tls.existingCASecretName` option](../../reference/helm-reference/teleport-cluster.mdx#tlsexistingcasecretname)), + or if the certificate was issued by a CA included in the [Mozilla CA Certificate List](https://wiki.mozilla.org/CA/Included_Certificates). + +Create a ConfigMap containing the CA certificate as follows: + +```code +$ kubectl -n create configmap teleport-access-graph-ca \ + --from-file=ca.pem=./certs/ca.crt +``` + +Then, update the values for the deployment of the `teleport-cluster` Helm chart as follows: + +```yaml +auth: + teleportConfig: + # <...> + + # Add a section for configuring the Teleport Access Graph connection. + access_graph: + enabled: true + endpoint: teleport-access-graph.teleport-access-graph.svc.cluster.local:443 + # Omit the `ca` key if your Teleport cluster already trusts the issuing CA. + ca: /var/run/access-graph/ca.pem + +# Provide the TAG CA to the Teleport Auth Service as a volume. +# Omit all of the below if your Teleport cluster already trusts the issuing CA. +extraVolumes: + - name: tag-ca + configMap: + name: teleport-access-graph-ca + +extraVolumeMounts: + - name: tag-ca + mountPath: /var/run/access-graph +``` + +If not using the `teleport-cluster` Helm chart, you will need to do the equivalent changes to your Teleport cluster deployment: +- Add the `access_graph:` section at the top-level of the YAML config file for the Teleport Auth Service. +- Mount the created ConfigMap as a volume so that the Auth Service can read the CA certificate. + +Finally, redeploy the Helm chart (assuming the values are stored in `values-teleport.yaml`). +Once the Auth Service changes succeed, restart the Proxy Service. + +```code +$ helm upgrade -n -f values-teleport.yaml \ + --version teleport/teleport-cluster +$ kubectl -n rollout status deployment/teleport-auth # Wait for the deployment to succeed +$ kubectl -n rollout restart deployment/teleport-proxy +$ kubectl -n rollout status deployment/teleport-proxy # Wait for the deployment to succeed +``` + +## Step 4/4. View the Access Graph in the Web UI + +You can find the Access Graph in the "Access Management" tab in the Web UI. +![Access Management menu item](../../../img/access-graph/menu-item.png) + +To access the interface, your user must have a role that allows `list` and `read` verbs on the `access_graph` resource, e.g.: + +```yaml +kind: role +version: v7 +metadata: + name: my-role +spec: + allow: + rules: + - resources: + - access_graph + verbs: + - list + - read +``` + +The preset `editor` role has the required permissions by default. diff --git a/docs/pages/access-controls/access-graph/self-hosted.mdx b/docs/pages/access-controls/access-graph/self-hosted.mdx index 485646cedc980..ee41f840072fc 100644 --- a/docs/pages/access-controls/access-graph/self-hosted.mdx +++ b/docs/pages/access-controls/access-graph/self-hosted.mdx @@ -22,17 +22,17 @@ by signing up for a [Teleport Team trial](https://goteleport.com/signup/). - Docker version v(=docker.version=) or later. - A PostgreSQL database server v14 or later. - Access Graph needs a dedicated [database](https://www.postgresql.org/docs/current/sql-createdatabase.html) to store its data. - The user that TAG connects to the database with needs to be an owner of this database, or have similar broad permissions: + The user that TAG connects to the database with needs to be the owner of this database, or have similar broad permissions: at least the `CREATE TABLE` privilege on the `public` schema, and the `CREATE SCHEMA` privilege. - Amazon RDS for PostgreSQL is supported. - A TLS certificate for the Access Graph service - The TLS certificate must be issued for "server authentication" key usage, and must list the IP or DNS name of the TAG service in an X.509 v3 `subjectAltName` extension. -- The node running the Access Graph service must be reachable from Teleport Auth and Proxy services. +- The node running the Access Graph service must be reachable from Teleport Auth Service and Proxy Service. ## Step 1/3. Set up the Teleport Access Graph service -You'll need a copy of your Teleport cluster's host certificate authority (CA) on the machine that hosts the Access Graph service. +You will need a copy of your Teleport cluster's host certificate authority (CA) on the machine that hosts the Access Graph service. TAG requires incoming connections to be authenticated via host certificates that the host CA issues to the Auth Service and Proxy Service. The host CA can be retrieved and saved into a file in one of the following ways: @@ -65,7 +65,7 @@ backend: # A stricter `sslmode` value is strongly recommended, # e.g. `sslmode=verify-full&sslrootcert=/etc/access_graph/my_postgres_ca.crt`. # For a full reference on possible parameters see https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS - connection: postgres://access_graph_user:mypassword@db.example.com:5432/access_graph_db?sslmode=require + connection: postgres://access_graph_user:my_password@db.example.com:5432/access_graph_db?sslmode=require # When running on Amazon RDS, IAM auth via credentials set in the environment can be used as follows: # iam: @@ -117,7 +117,7 @@ To access the interface, your user must have a role that allows `list` and `read ```yaml kind: role -version: v6 +version: v7 metadata: name: my-role spec: diff --git a/docs/pages/reference/helm-reference.mdx b/docs/pages/reference/helm-reference.mdx index ed3603942312f..46206f58789e0 100644 --- a/docs/pages/reference/helm-reference.mdx +++ b/docs/pages/reference/helm-reference.mdx @@ -10,6 +10,8 @@ layout: tocless-doc - [teleport-kube-agent](./helm-reference/teleport-kube-agent.mdx): Deploy the Teleport Kubernetes Service, Application Service, or Database Service on Kubernetes. +- [teleport-access-graph](./helm-reference/teleport-access-graph.mdx): Deploy the + Teleport Access Graph service. - [teleport-plugin-event-handler](./helm-reference/teleport-plugin-event-handler.mdx): Deploy the Teleport Event Handler plugin which sends events and session logs to Fluentd. diff --git a/docs/pages/reference/helm-reference/includes/zz_generated.teleport-access-graph.mdx b/docs/pages/reference/helm-reference/includes/zz_generated.teleport-access-graph.mdx new file mode 100644 index 0000000000000..ebf3e078a56ad --- /dev/null +++ b/docs/pages/reference/helm-reference/includes/zz_generated.teleport-access-graph.mdx @@ -0,0 +1,152 @@ + +## `tls` + +`tls` TLS settings for the main gRPC listener. + +### `tls.existingSecretName` + +| Type | Default | +|------|---------| +| `string` | `""` | + +`tls.existingSecretName` is the name of an existing Kubernetes secret +containing the certificate and its private key to use for the gRPC listener. +The secret must be of type `kubernetes.io/tls`, see +[the Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets) for more details. + +Setting this is required, as Teleport Access Graph always operates via TLS-protected connections. + +## `clusterHostCAs` + +| Type | Default | +|------|---------| +| `array` | `[]` | + +`clusterHostCAs` is a list of strings containing PEM-encoded Host CA certificates of Teleport clusters that are allowed to use this instance of TAG. +Setting this to a non-empty array is required. + +## `service` + +| Type | Default | +|------|---------| +| `object` | `{"grpcPort":443,"type":"ClusterIP"}` | + +`service` contains options for the TAG Kubernetes service that the Chart exposes. + +### `service.type` + +| Type | Default | +|------|---------| +| `string` | `"ClusterIP"` | + +`service.type` the type of Kubernetes service to create. +The `LoadBalancer` type is only supported when using a Layer 4 (TCP) or lower load balancer. +TAG expects to terminate its own TLS, as it uses mTLS to authenticate its clients. + +### `service.grpcPort` + +| Type | Default | +|------|---------| +| `int` | `443` | + +`service.grpcPort` the port that the gRPC service is exposed on. +This is the port that Teleport Auth Service and Proxy Service will need to connect to TAG on. + +## `replicaCount` + +| Type | Default | +|------|---------| +| `int` | `2` | + +`replicaCount` the number of TAG pods that should be deployed. + +## `image` + +### `image.tag` + +| Type | Default | +|------|---------| +| `string` | `""` | + +`image.tag` sets the version of the Teleport Access Graph image used. +By default, this is the same as the Helm Chart version, i.e. TAG will be upgraded when you upgrade the Helm chart. + +## `podAnnotations` + +| Type | Default | +|------|---------| +| `object` | `{}` | + +`podAnnotations` contains the Kubernetes annotations put on the `Pod` resources created by the chart. + +## `podLabels` + +| Type | Default | +|------|---------| +| `object` | `{}` | + +`podLabels` contains the Kubernetes labels put on the `Pod` resources created by the chart. + +## `podSecurityContext` + +| Type | Default | +|------|---------| +| `object` | `{"runAsGroup":65532,"runAsNonRoot":true,"runAsUser":65532}` | + +`podSecurityContext` sets the pod security context for any pods created by the chart. +See [the Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-pod) +for more details. + +The default value supports running under the `restricted` +[Pod Security Standard](https://kubernetes.io/docs/concepts/security/pod-security-standards/). + +## `securityContext` + +| Type | Default | +|------|---------| +| `object` | `{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]},"seccompProfile":{"type":"RuntimeDefault"}}` | + +`securityContext` sets the container security context for any pods created by the chart. +See [the Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-container) +for more details. + +The default value supports running under the `restricted` +[Pod Security Standard](https://kubernetes.io/docs/concepts/security/pod-security-standards/). + +## `volumes` + +| Type | Default | +|------|---------| +| `array` | `[]` | + +`volumes` allows to define additional volumes on the output Deployment definition. + +## `nodeSelector` + +| Type | Default | +|------|---------| +| `object` | `{}` | + +`nodeSelector` sets the node selector for any pods created by the chart. +See [the Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) +for more details. + +## `tolerations` + +| Type | Default | +|------|---------| +| `list` | `[]` | + +`tolerations` sets the tolerations for any pods created by the chart. +See [the Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) +for more details. + +## `affinity` + +| Type | Default | +|------|---------| +| `object` | `{}` | + +`affinity` sets the affinities for any pods created by the chart. +See [the Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) +for more details. diff --git a/docs/pages/reference/helm-reference/teleport-access-graph.mdx b/docs/pages/reference/helm-reference/teleport-access-graph.mdx new file mode 100644 index 0000000000000..ea7fb54acad25 --- /dev/null +++ b/docs/pages/reference/helm-reference/teleport-access-graph.mdx @@ -0,0 +1,19 @@ +--- +title: teleport-access-graph Chart Reference +description: Values that can be set using the teleport-access-graph Helm chart +--- + +The `teleport-access-graph` Helm chart deploys the Teleport Access Graph service. + +See [Run Teleport Access Graph on Self-Hosted Clusters with Helm](../../access-controls/access-graph/self-hosted-helm.mdx) +for more details. + + +The chart is versioned with the Teleport Access Graph service. No compatibility +guarantees are ensured if the service and chart versions differ. +It is strongly recommended to always align the chart and service versions +by using the `--version` Helm flag. + + + +(!docs/pages/reference/helm-reference/includes/zz_generated.teleport-access-graph.mdx!)