diff --git a/docs/reference/configuration/credentials-operator/README.mdx b/docs/reference/configuration/credentials-operator/README.mdx index a949a738b..14b255b81 100644 --- a/docs/reference/configuration/credentials-operator/README.mdx +++ b/docs/reference/configuration/credentials-operator/README.mdx @@ -32,7 +32,7 @@ To learn more, check out the documentation for [SPIRE](https://spiffe.io/docs/la | `credentials-operator.otterize.com/truststore-file-name` | Truststore key name in the secret. When mounted, this is the filename for the truststore. Only used when cert-type is `jks`. | `truststore.jks` | | `credentials-operator.otterize.com/jks-password` | Password for the JKS truststore and keystore. Only used when cert-type is `jks`. | `password` | | `credentials-operator.otterize.com/restart-pod-on-certificate-renewal` | A pod with this annotation (no matter the value) will be restarted after certificate renewal, along with any replicas. Should be ideally set through the pod owner's `template` spec so it will persist between restarts. | N/A | -| `intents.otterize.com/service-name` | Otterize-wide override for this service's name. Used by the operator when registering the service with SPIRE and generating credentials. | See [Service identities](/reference/service-identities) | +| `intents.otterize.com/service-name` | Used for [service identity resolution](/reference/service-identities#kubernetes-service-identity-resolution).| | ## How does the credentials operator work? @@ -46,9 +46,6 @@ The operator consults the label `credentials-operator.otterize.com/tls-secret-na When using SPIRE, once the operator has registered the pod with SPIRE, which happens automatically upon startup, the pod can use the SPIRE Workload API to generate credentials for the SVID `.`. ### Service name resolution and automatic pod labeling -Service name resolution is performed one of two ways: -1. If an `intents.otterize.com/service-name` annotation is present, that name is used. -2. If not, a recursive look up is performed for the Kubernetes resource owner for a Pod until the root is reached. For example, if you have a `Deployment` named `client`, which then creates and owns a `ReplicaSet`, which then creates and owns a `Pod`, then the service name for that pod is `client` - same as the name of the `Deployment`. - -The value resulting from this process forms the value of the label `credentials-operator.otterize.com/service-name`. +The operator performs service name resolution for each pod. You can read more about the resolution algorithm [here](/reference/service-identities#kubernetes-service-identity-resolution). +The value resulting from this resolution process forms the value of the label `credentials-operator.otterize.com/service-name`. diff --git a/docs/reference/configuration/credentials-operator/helm-chart.mdx b/docs/reference/configuration/credentials-operator/helm-chart.mdx index b0d994d38..98b8509e8 100644 --- a/docs/reference/configuration/credentials-operator/helm-chart.mdx +++ b/docs/reference/configuration/credentials-operator/helm-chart.mdx @@ -23,6 +23,7 @@ If you would like to deploy it on its own, add the Otterize Helm chart repositor | `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 diff --git a/docs/reference/configuration/intents-operator/README.mdx b/docs/reference/configuration/intents-operator/README.mdx index 4c80414b4..88fb9557c 100644 --- a/docs/reference/configuration/intents-operator/README.mdx +++ b/docs/reference/configuration/intents-operator/README.mdx @@ -26,9 +26,9 @@ To learn how to use the intents operator to control access, consult the guides f You can override the service name the intents operator uses when it computes network policies and Kafka ACLs with a pod annotation. -| Annotation | Description | Default | -|-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------| -| `intents.otterize.com/service-name` | Otterize-wide override for this service's name. Used by the operator when computing a pod's service name for use in network policies and Kafka ACLs. | See [Service identities](/reference/service-identities) | +| Annotation | Description | +|-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| +| `intents.otterize.com/service-name` | Used for [service identity resolution](/reference/service-identities#kubernetes-service-identity-resolution).| ## Supported enforcement types diff --git a/docs/reference/configuration/intents-operator/helm-chart.mdx b/docs/reference/configuration/intents-operator/helm-chart.mdx index d75754daa..2afcac06e 100644 --- a/docs/reference/configuration/intents-operator/helm-chart.mdx +++ b/docs/reference/configuration/intents-operator/helm-chart.mdx @@ -20,11 +20,12 @@ If you would like to deploy it on its own, add the Otterize Helm chart repositor | Key | Description | Default | |:---------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------|---------| | `global.allowGetAllResources` | If defined overrides `allowGetAllResources`. | | -| `global.telemetry.enabled` | If set to `false`, anonymous telemetries collection will be disabled | `true` | -| `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.telemetry.enabled` | If set to `false`, anonymous telemetries collection will be disabled. | `true` | +| `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` | ## Operator parameters diff --git a/docs/reference/configuration/network-mapper/README.mdx b/docs/reference/configuration/network-mapper/README.mdx index 8c48e2ff7..bc3941d17 100644 --- a/docs/reference/configuration/network-mapper/README.mdx +++ b/docs/reference/configuration/network-mapper/README.mdx @@ -63,6 +63,6 @@ To deploy the network mapper, [use the Helm chart](/reference/configuration/netw You can override the service name the network mapper uses when it computes the service name using a pod annotation. -| Annotation | Description | Default | -|-------------------------------------|-------------------------------------------------|-----------------------------------------------| -| `intents.otterize.com/service-name` | Otterize-wide override for this service's name. | See [Service identities](/reference/service-identities) | +| Annotation | Description | +|-------------------------------------|-------------------------------------------------| +| `intents.otterize.com/service-name` | Used for [service identity resolution](/reference/service-identities#kubernetes-service-identity-resolution). | diff --git a/docs/reference/configuration/network-mapper/helm-chart.mdx b/docs/reference/configuration/network-mapper/helm-chart.mdx index 1497b04de..e65e0b1aa 100644 --- a/docs/reference/configuration/network-mapper/helm-chart.mdx +++ b/docs/reference/configuration/network-mapper/helm-chart.mdx @@ -76,6 +76,7 @@ Checkout the network mapper [tutorial](/quick-tutorials/k8s-network-mapper) to s | `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` | ## Common parameters diff --git a/docs/reference/configuration/otterize-chart/README.mdx b/docs/reference/configuration/otterize-chart/README.mdx index 84c6c0981..2483eff20 100644 --- a/docs/reference/configuration/otterize-chart/README.mdx +++ b/docs/reference/configuration/otterize-chart/README.mdx @@ -33,6 +33,8 @@ These parameters are used by multiple charts, and must be kept the same for the | `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` | + ## Cloud parameters | Key | Description | Default | diff --git a/docs/reference/service-identities/README.mdx b/docs/reference/service-identities/README.mdx index b39fb710d..324a48dd2 100644 --- a/docs/reference/service-identities/README.mdx +++ b/docs/reference/service-identities/README.mdx @@ -8,11 +8,11 @@ Otterize uses universal service identities to refer to services, regardless of w ## Kubernetes service identity resolution How do Otterize operators decide what is the name of the service that runs within the pod? The algorithm is as follows: -1. If the pod has an `intents.otterize.com/service-name` label, its value is used as the service name. This allows developers and +1. If the pod has an `intents.otterize.com/service-name` annotation, its value is used as the service name. (You can change which annotation is used by setting `global.serviceNameOverrideAnnotationName` — see the [docs](/reference/configuration/otterize-chart#global-parameters).) This allows developers and automations to explicitly name services, if needed. The value must not contain a period `.` as a period is used to separate service name and namespace, when the service is from a different namespace: `svcname.namespace`. -2. If there is no `intents.otterize.com/service-name` label, a recursive look-up is performed for the Kubernetes resource owner of +2. If there is no `intents.otterize.com/service-name` annotation, a recursive look-up is performed for the Kubernetes resource owner of the pod, until the root resource is reached, and its name is used as the service name. For example, if you have a `Deployment` named `checkoutservice`, which then creates and owns a `ReplicaSet`, which then creates and owns a `Pod`, then the service name for that pod is `checkoutservice` - same as the name of the `Deployment`. This is intended to capture the likely-more-meaningful "human name" of the service. If the resulting service name contains - a period `.`, it is replaced with an underscore `_`. Periods are used in service names to denote namespaces, e.g. `svcname.namespace`. \ No newline at end of file + a period `.`, it is replaced with an underscore `_`. Periods are used in service names to denote namespaces, e.g. `svcname.namespace`.