Skip to content

Commit

Permalink
Update docs with new field credentialsProvider that also supports "…
Browse files Browse the repository at this point in the history 
…cert-manager"

instead of the old `useCloudToGenerateTLSCredentials`
  • Loading branch information
@roekatz
roekatz committed Aug 28, 2023
1 parent 5ccc910 commit 256c559
Show file tree
Hide file tree
Showing 4 changed files with 29 additions and 15 deletions.
2 changes: 1 addition & 1 deletion docs/reference/configuration/credentials-operator/README.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
30 changes: 19 additions & 11 deletions docs/reference/configuration/credentials-operator/helm-chart.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -38,21 +39,28 @@ 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)` |
| `global.otterizeCloud.credentials.secretKeyRef.secretKey` | If specified, the key for the clientSecret in a pre-created Kubernetes Secret to be used instead of creating a secret with the value of clientSecret. | `(none)` |
| `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 |
|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
Expand Down
6 changes: 5 additions & 1 deletion docs/reference/configuration/otterize-chart/README.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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` |
Expand All @@ -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)` |
Expand Down Expand Up @@ -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 |
|----------------------------|--------------------------------------|----------|
Expand Down
6 changes: 4 additions & 2 deletions docs/security/README.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down

0 comments on commit 256c559

Please sign in to comment.