From 256c559d751e66955d288624a5c8415fca56b69b Mon Sep 17 00:00:00 2001 From: Ro'e Katz Date: Mon, 28 Aug 2023 17:48:36 +0300 Subject: [PATCH] Update docs with new field `credentialsProvider` that also supports "cert-manager" instead of the old `useCloudToGenerateTLSCredentials` --- .../credentials-operator/README.mdx | 2 +- .../credentials-operator/helm-chart.mdx | 30 ++++++++++++------- .../configuration/otterize-chart/README.mdx | 6 +++- docs/security/README.mdx | 6 ++-- 4 files changed, 29 insertions(+), 15 deletions(-) diff --git a/docs/reference/configuration/credentials-operator/README.mdx b/docs/reference/configuration/credentials-operator/README.mdx index 14b255b81..0fad5f519 100644 --- a/docs/reference/configuration/credentials-operator/README.mdx +++ b/docs/reference/configuration/credentials-operator/README.mdx @@ -38,7 +38,7 @@ To learn more, check out the documentation for [SPIRE](https://spiffe.io/docs/la ### SPIRE entry registration Once the operator [resolves the service name](#service-name-resolution-and-automatic-pod-labeling) for a pod, it labels the pod and registers an entry with the SPIRE server. -If configured to use Otterize Cloud credentials instead of SPIRE (`useCloudToGenerateTLSCredentials` in the Helm chart configuration), it registers the Otterize service with Otterize Cloud. +If configured to use Otterize Cloud credentials instead of SPIRE (`global.credentialsProvider=otterize-cloud` in the Helm chart configuration), it registers the Otterize service with Otterize Cloud. ### Credential generation The operator consults the label `credentials-operator.otterize.com/tls-secret-name`. If that label exists, the operator creates a secret named after the value of the label with X.509 credentials within, provided by SPIRE or Otterize Cloud, depending on how the credentials operator is configured. This way, the pod can get autogenerated credentials without modifying its code. diff --git a/docs/reference/configuration/credentials-operator/helm-chart.mdx b/docs/reference/configuration/credentials-operator/helm-chart.mdx index 98b8509e8..a52fe3e32 100644 --- a/docs/reference/configuration/credentials-operator/helm-chart.mdx +++ b/docs/reference/configuration/credentials-operator/helm-chart.mdx @@ -15,16 +15,17 @@ If you would like to deploy it on its own, add the Otterize Helm chart repositor # Parameters ## Global parameters -| Key | Description | Default | -|--------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|---------| -| `global.spire.serverServiceName` | If deployed with SPIRE, this key specifies SPIRE-server's service name. You should use either this **OR** `spire.serverAddress` (not both). | | -| `global.allowGetAllResources` | If defined overrides `allowGetAllResources`. | | | `false` | -| `global.commonAnnotations` | Annotations to add to all deployed objects | {} | -| `global.commonLabels` | Labels to add to all deployed objects | {} | -| `global.podAnnotations` | Annotations to add to all deployed pods | {} | -| `global.podLabels` | Labels to add to all deployed pods | {} | -| `global.serviceNameOverrideAnnotationName` | Which annotation to use (in the [service name resolution algorithm](/reference/service-identities#kubernetes-service-identity-resolution)) for setting a pod's service name, if not the default. Use this if you already have annotations on your pods that provide the correct service name. | `intents.otterize.com/service-name` | +| Key | Description | Default | +|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|-----------| +| `global.credentialsProvider` | What provider should be used to generate certificates/credentials - `"spire"`, `"otterize-cloud"` or `"cert-manager"` | `"spire"` | +| `global.spire.serverServiceName` | If deployed with SPIRE, this key specifies SPIRE-server's service name. You should use either this **OR** `spire.serverAddress` (not both). | | +| `global.allowGetAllResources` | If defined overrides | `false` | +| `global.commonAnnotations` | Annotations to add to all deployed objects | {} | +| `global.commonLabels` | Labels to add to all deployed objects | {} | +| `global.podAnnotations` | Annotations to add to all deployed pods | {} | +| `global.podLabels` | Labels to add to all deployed pods | {} | +| `global.serviceNameOverrideAnnotationName` | Which annotation to use (in the [service name resolution algorithm](/reference/service-identities#kubernetes-service-identity-resolution)) for setting a pod's service name, if not the default. Use this if you already have annotations on your pods that provide the correct service name. | `intents.otterize.com/service-name` | ## SPIRE parameters @@ -38,14 +39,14 @@ If you would like to deploy it on its own, add the Otterize Helm chart repositor | Key | Description | Default | |-----------------------------|----------------------------|------------------------------| | `operator.image.repository` | Operator image repository. | `otterize` | -| `operator.image.image` | Operator image. | `credentials-operator` | +| `operator.image.image` | Operator image. | `credentials-operator` | | `operator.image.tag` | Operator image tag. | `latest` | | `operator.pullPolicy` | Operator pull policy. | `(none)` | ## Cloud parameters + | Key | Description | Default | |------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------| -| `global.otterizeCloud.useCloudToGenerateTLSCredentials` | Use Otterize Cloud for certificate management instead of SPIRE | `false` | | `global.otterizeCloud.credentials.clientId` | Client ID for connecting to Otterize Cloud. | `(none)` | | `global.otterizeCloud.credentials.clientSecret` | Client secret for connecting to Otterize Cloud. | `(none)` | | `global.otterizeCloud.credentials.secretKeyRef.secretName` | If specified, the name of a pre-created Kubernetes Secret to be used instead of creating a secret with the value of clientSecret. | `(none)` | @@ -53,6 +54,13 @@ If you would like to deploy it on its own, add the Otterize Helm chart repositor | `global.otterizeCloud.apiAddress` | Overrides Otterize Cloud default API address. | `(none)` | | `global.otterizeCloud.apiExtraCAPEMSecret` | The name of a secret containing a single `CA.pem` file for an extra root CA used to connect to Otterize Cloud. The secret should be placed in the same namespace as the Otterize deployment. | `(none)` | +## cert-manager parameters + +| Key | Description | Default | +|--------------------------------|---------------------------------------------------------------------------------------------------------------|---------| +| `certManager.issuerName` | The cert-manager Issuer (or ClusterIssuer if `useClusterIssuer` is set) to be used for certificate generation | `""` | +| `certManager.useClusterIssuer` | Use ClusterIssuer instead of the namespace scoped Issuer. | `false` | + ## Common parameters | Key | Description | Default | |------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------| diff --git a/docs/reference/configuration/otterize-chart/README.mdx b/docs/reference/configuration/otterize-chart/README.mdx index 2483eff20..3ca2cdd95 100644 --- a/docs/reference/configuration/otterize-chart/README.mdx +++ b/docs/reference/configuration/otterize-chart/README.mdx @@ -26,6 +26,7 @@ These parameters are used by multiple charts, and must be kept the same for the | `global.spiffe.CASubject.country` | SPIRE's CA certificates `Country` value. | `"US"` | | `global.spiffe.CASubject.organization` | SPIRE's CA certificates `Organization` Value. | `"SPIRE"` | | `global.spiffe.trustDomain` | The trust domain that SPIRE will use. | `"example.org"` | +| `global.credentialsProvider` | What provider should be used to generate certificates/credentials - `"spire"`, `"otterize-cloud"` or `"cert-manager"` | `"spire"` | | `global.spire.serverServiceName` | Name of the Kubernetes service that will be created for SPIRE-server. | | | `global.allowGetAllResources` | If defined overrides `allowGetAllResources` in subcharts. Gives get, list and watch permission to watch on all resources. This is used to resolve service names when pods have owners that are custom resources. When disabled, a limited set of permissions is used that only allows access to built-in Kubernetes resources that deploy Pods and Pods themselves - Deployments, StatefulSets, DaemonSets, ReplicaSets and Services. Resolving may not be able to complete if the owning resource is not one of those. | | | `global.telemetry.enabled` | If set to `false`, anonymous telemetries collection will be disabled | `true` | @@ -39,7 +40,6 @@ These parameters are used by multiple charts, and must be kept the same for the ## Cloud parameters | Key | Description | Default | |------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------| -| `global.otterizeCloud.useCloudToGenerateTLSCredentials` | Use Otterize Cloud for certificate management instead of SPIRE. | `false` | | `global.otterizeCloud.credentials.clientId` | Client ID for connecting to Otterize Cloud. | `(none)` | | `global.otterizeCloud.credentials.clientSecret` | Client secret for connecting to Otterize Cloud. | `(none)` | | `global.otterizeCloud.credentials.secretKeyRef.secretName` | If specified, the name of a pre-created Kubernetes Secret to be used instead of creating a secret with the value of clientSecret. | `(none)` | @@ -78,6 +78,10 @@ Further information about `SPIRE` parameters can be found [in SPIRE's Helm chart All configurable parameters of the network mapper can be configured under the alias `networkMapper`. Further information about network mapper parameters can be found [in the network mapper's chart](https://github.com/otterize/helm-charts/tree/main/network-mapper). +## Credentials operator parameters +All configurable parameters of the credentials operator can be configured under the alias `credentialsOperator`. +Further information about network mapper parameters can be found [in the network mapper's chart](https://github.com/otterize/helm-charts/tree/main/credentials-operator). + ## Resource configuration | Component | Key | Default | |----------------------------|--------------------------------------|----------| diff --git a/docs/security/README.mdx b/docs/security/README.mdx index fc7426799..a5c1d591b 100644 --- a/docs/security/README.mdx +++ b/docs/security/README.mdx @@ -103,11 +103,13 @@ The service names in each namespace are set by the developers, or the platform t ### Cryptographic credentials -The cryptographic credentials created by the Otterize credentials operator (mTLS certificate and key pairs) are provided in one of two ways, depending on how the operator is configured: +The cryptographic credentials created by the Otterize credentials operator (mTLS certificate and key pairs) are provided in one of three ways, depending on how the operator is configured: 1. By a SPIRE server that is deployed alongside the credentials operator. 2. By the Otterize Cloud managed credentials service. That service is built on a Hashicorp Vault instance with a CA automatically created for you. Using Otterize Cloud for credentials means you do not need to deploy SPIRE on your cluster, which makes for a simpler and lightweight deployment. +3. By an independently deployed [cert-manager](https://github.com/cert-manager/cert-manager) operator. -Note that, by default, the first option (in-cluster SPIRE) is used, even when the credentials operator is connected to Otterize Cloud). The `useCloudToGenerateTLSCredentials` must be set to `true` to use Cloud-managed credentials; see the [Helm chart configuration for the credentials operator](/reference/configuration/credentials-operator/helm-chart#cloud-parameters) for more details. +Note that, by default, the first option (in-cluster SPIRE) is used, even when the credentials operator is connected to Otterize Cloud). +The `credentialsProvider` could be set to `otterize-cloud` or `cert-manager` to use the other options; see the [Helm chart configuration for the credentials operator](/reference/configuration/credentials-operator/helm-chart#cloud-parameters) for more details. The credentials operator watches for pods starting up in a Kubernetes cluster, and if mTLS credentials are requested, it uses the [resolved or declared service name](/reference/service-identities) plus the pod’s namespace to generate credentials for that service name, in that namespace. The operator is conceptually similar to a SPIRE agent in that it attests to the identity of pods.