You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by mm...@apache.org on 2023/05/12 22:11:20 UTC
[pulsar-site] branch main updated: Add documentation for KubernetesServiceAccountTokenAuthProvider (#570)
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 <mm...@apache.org>
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
+:::