This is an automated email from the ASF dual-hosted git repository.
mmarshall pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git
The following commit(s) were added to refs/heads/main by this push:
new f7c11ad1000 Add documentation for
KubernetesServiceAccountTokenAuthProvider (#570)
f7c11ad1000 is described below
commit f7c11ad1000fe2536ec98d0cd27f6a9c592a75e6
Author: Michael Marshall <[email protected]>
AuthorDate: Fri May 12 17:11:15 2023 -0500
Add documentation for KubernetesServiceAccountTokenAuthProvider (#570)
* Add documentation for KubernetesServiceAccountTokenAuthProvider
* Port new docs to 3.0.x
* Address comments from review
---
docs/functions-runtime-kubernetes.md | 56 +++++++++++++++++++++-
.../version-3.0.x/functions-runtime-kubernetes.md | 56 +++++++++++++++++++++-
2 files changed, 110 insertions(+), 2 deletions(-)
diff --git a/docs/functions-runtime-kubernetes.md
b/docs/functions-runtime-kubernetes.md
index a7bec7da7a7..0d0da513840 100644
--- a/docs/functions-runtime-kubernetes.md
+++ b/docs/functions-runtime-kubernetes.md
@@ -65,6 +65,60 @@ If the token you use to deploy the function has an
expiration date, you may need
:::
+### Enable Kubernetes service account token projection for function pod
authentication
+
+The `KubernetesServiceAccountTokenAuthProvider` uses [service account token
volume
projections](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#serviceaccount-token-volume-projection)
to mount a token into the function's pod. The function worker and broker can
verify this token using OpenID Connect. The primary benefit of this integration
is that tokens have a short time to live, are managed by Kubernetes, and do not
inherit the permission used to crea [...]
+
+:::note
+
+This feature requires that the broker and the function worker are configured
to use the `AuthenticationProviderOpenID`. Documentation to enable this
provider can be found [here](security-openid-connect.md).
+
+:::
+
+Here is an example configuration for the function worker to utilize this
feature:
+
+```yaml
+functionAuthProviderClassName:
"org.apache.pulsar.functions.auth.KubernetesServiceAccountTokenAuthProvider"
+kubernetesContainerFactory:
+ kubernetesFunctionAuthProviderConfig:
+ # Required
+ serviceAccountTokenExpirationSeconds: "600"
+ serviceAccountTokenAudience: "the-required-audience"
+ # Optional
+ brokerClientTrustCertsSecretName:
"my-secret-pulsar-broker-client-trust-certs"
+```
+
+The function pod deploys with the default Kubernetes service account for the
target namespace. Because the service account name maps to the `sub` claim on
the JWT projected into the pod's filesystem, all pods with the same service
account will have the same permission within Pulsar. There is ongoing work to
improve this integration.
+
+Here is a sample JWT generated by this feature running in EKS (with some
information redacted):
+
+```json
+{
+ "aud": [
+ "your-audience"
+ ],
+ "exp": 1710969822,
+ "iat": 1679433822,
+ "iss": "https://oidc.eks.us-east-2.amazonaws.com/id/some-id";,
+ "kubernetes.io": {
+ "namespace": "pulsar-function",
+ "pod": {
+ "name": "function-pod-0",
+ "uid": "fbac8f9e-a47d-4ad7-a8f0-cc9a65d1331c"
+ },
+ "serviceaccount": {
+ "name": "default",
+ "uid": "5964f9d3-3dce-467c-8dbe-d0f463063d7a"
+ },
+ "warnafter": 1679437429
+ },
+ "nbf": 1679433822,
+ "sub": "system:serviceaccount:pulsar-function:default"
+}
+```
+
+To grant permission to this function pod, you need to grant permissions to the
role claim, which is the `sub` claim by default,
`system:serviceaccount:pulsar-function:default`.
+
### Customize Kubernetes runtime
Customizing Kubernetes runtime allows you to customize Kubernetes resources
created by the runtime, including how to generate manifests, how to pass
authenticated data to pods, and how to integrate secrets.
@@ -141,4 +195,4 @@ Kubernetes requires a name that can be used as a DNS
subdomain name as defined i
- If you get an error in translating Pulsar object names into Kubernetes
resource labels (for example, you may have a naming collision if your Pulsar
object name is too long) or want to customize the translating rules, see
[customize Kubernetes
runtime](functions-runtime-kubernetes.md#customize-kubernetes-runtime).
- For how to configure Kubernetes runtime, see
[instructions](functions-runtime-kubernetes.md).
-:::
\ No newline at end of file
+:::
diff --git a/versioned_docs/version-3.0.x/functions-runtime-kubernetes.md
b/versioned_docs/version-3.0.x/functions-runtime-kubernetes.md
index a7bec7da7a7..0d0da513840 100644
--- a/versioned_docs/version-3.0.x/functions-runtime-kubernetes.md
+++ b/versioned_docs/version-3.0.x/functions-runtime-kubernetes.md
@@ -65,6 +65,60 @@ If the token you use to deploy the function has an
expiration date, you may need
:::
+### Enable Kubernetes service account token projection for function pod
authentication
+
+The `KubernetesServiceAccountTokenAuthProvider` uses [service account token
volume
projections](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#serviceaccount-token-volume-projection)
to mount a token into the function's pod. The function worker and broker can
verify this token using OpenID Connect. The primary benefit of this integration
is that tokens have a short time to live, are managed by Kubernetes, and do not
inherit the permission used to crea [...]
+
+:::note
+
+This feature requires that the broker and the function worker are configured
to use the `AuthenticationProviderOpenID`. Documentation to enable this
provider can be found [here](security-openid-connect.md).
+
+:::
+
+Here is an example configuration for the function worker to utilize this
feature:
+
+```yaml
+functionAuthProviderClassName:
"org.apache.pulsar.functions.auth.KubernetesServiceAccountTokenAuthProvider"
+kubernetesContainerFactory:
+ kubernetesFunctionAuthProviderConfig:
+ # Required
+ serviceAccountTokenExpirationSeconds: "600"
+ serviceAccountTokenAudience: "the-required-audience"
+ # Optional
+ brokerClientTrustCertsSecretName:
"my-secret-pulsar-broker-client-trust-certs"
+```
+
+The function pod deploys with the default Kubernetes service account for the
target namespace. Because the service account name maps to the `sub` claim on
the JWT projected into the pod's filesystem, all pods with the same service
account will have the same permission within Pulsar. There is ongoing work to
improve this integration.
+
+Here is a sample JWT generated by this feature running in EKS (with some
information redacted):
+
+```json
+{
+ "aud": [
+ "your-audience"
+ ],
+ "exp": 1710969822,
+ "iat": 1679433822,
+ "iss": "https://oidc.eks.us-east-2.amazonaws.com/id/some-id";,
+ "kubernetes.io": {
+ "namespace": "pulsar-function",
+ "pod": {
+ "name": "function-pod-0",
+ "uid": "fbac8f9e-a47d-4ad7-a8f0-cc9a65d1331c"
+ },
+ "serviceaccount": {
+ "name": "default",
+ "uid": "5964f9d3-3dce-467c-8dbe-d0f463063d7a"
+ },
+ "warnafter": 1679437429
+ },
+ "nbf": 1679433822,
+ "sub": "system:serviceaccount:pulsar-function:default"
+}
+```
+
+To grant permission to this function pod, you need to grant permissions to the
role claim, which is the `sub` claim by default,
`system:serviceaccount:pulsar-function:default`.
+
### Customize Kubernetes runtime
Customizing Kubernetes runtime allows you to customize Kubernetes resources
created by the runtime, including how to generate manifests, how to pass
authenticated data to pods, and how to integrate secrets.
@@ -141,4 +195,4 @@ Kubernetes requires a name that can be used as a DNS
subdomain name as defined i
- If you get an error in translating Pulsar object names into Kubernetes
resource labels (for example, you may have a naming collision if your Pulsar
object name is too long) or want to customize the translating rules, see
[customize Kubernetes
runtime](functions-runtime-kubernetes.md#customize-kubernetes-runtime).
- For how to configure Kubernetes runtime, see
[instructions](functions-runtime-kubernetes.md).
-:::
\ No newline at end of file
+:::
