Skip to content

Commit c617663

Browse files
ivanauthivanauth
committed
Document extraServiceAccountAnnotations with AWS IRSA example
1 parent 8475347 commit c617663

4 files changed

Lines changed: 387 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 78 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ zed --insecure --endpoint=localhost:50051 --token=averysecretpresharedkey schema
8181

8282
## Where To Go From Here
8383

84-
- Check out the [examples](examples) directory to see how to configure `SpiceDBCluster` for production, including datastore backends, TLS, and Ingress.
84+
- Check out the [examples](examples) directory to see how to configure `SpiceDBCluster` for production, including datastore backends, TLS, Ingress, and cloud provider integrations.
8585
- Learn how to use SpiceDB via the [docs](https://docs.authzed.com/) and [playground](https://play.authzed.com/).
8686
- Ask questions and join the community in [discord](https://authzed.com/discord).
8787

@@ -134,6 +134,83 @@ The certificates will be available at these paths inside the SpiceDB containers:
134134

135135
Note: The exact SSL parameter names depend on your datastore's connection driver. Consult your datastore's documentation for the correct connection string format.
136136

137+
### Service Account Annotations
138+
139+
The `extraServiceAccountAnnotations` field allows you to add custom annotations to the ServiceAccount created for SpiceDB pods. This is particularly useful for cloud provider integrations that use workload identity.
140+
141+
#### AWS IAM Roles for Service Accounts (IRSA)
142+
143+
```yaml
144+
apiVersion: authzed.com/v1alpha1
145+
kind: SpiceDBCluster
146+
metadata:
147+
name: spicedb-with-irsa
148+
spec:
149+
config:
150+
datastoreEngine: postgres
151+
# Required for RDS IAM authentication
152+
datastoreCredentialsProviderName: "aws-iam"
153+
extraServiceAccountAnnotations:
154+
eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/spicedb-role"
155+
```
156+
157+
See the [AWS IAM Service Account example](examples/aws-iam-service-account/) for a complete guide on using IRSA with SpiceDB.
158+
159+
#### GCP Workload Identity
160+
161+
```yaml
162+
apiVersion: authzed.com/v1alpha1
163+
kind: SpiceDBCluster
164+
metadata:
165+
name: spicedb-with-workload-identity
166+
spec:
167+
config:
168+
datastoreEngine: postgres
169+
extraServiceAccountAnnotations:
170+
iam.gke.io/gcp-service-account: "spicedb@my-project.iam.gserviceaccount.com"
171+
```
172+
173+
#### Azure Workload Identity
174+
175+
```yaml
176+
apiVersion: authzed.com/v1alpha1
177+
kind: SpiceDBCluster
178+
metadata:
179+
name: spicedb-with-azure-wi
180+
spec:
181+
config:
182+
datastoreEngine: postgres
183+
extraServiceAccountAnnotations:
184+
azure.workload.identity/client-id: "<AZURE_CLIENT_ID>"
185+
```
186+
187+
### Custom Service Account Name
188+
189+
You can specify a custom service account name using the `serviceAccountName` field:
190+
191+
```yaml
192+
spec:
193+
config:
194+
serviceAccountName: "my-custom-spicedb-sa"
195+
extraServiceAccountAnnotations:
196+
eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/spicedb-role"
197+
```
198+
199+
### Pod Labels and Annotations
200+
201+
You can also add custom labels and annotations to SpiceDB pods:
202+
203+
```yaml
204+
spec:
205+
config:
206+
extraPodLabels:
207+
environment: "production"
208+
team: "platform"
209+
extraPodAnnotations:
210+
prometheus.io/scrape: "true"
211+
prometheus.io/port: "9090"
212+
```
213+
137214
## Automatic and Suggested Updates
138215

139216
The SpiceDB operator now ships with a set of release channels for SpiceDB.

‎examples/aws-iam-service-account/README.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
# AWS IAM Roles for Service Accounts (IRSA) with SpiceDB
2+
3+
This example demonstrates how to configure SpiceDB to use AWS IAM Roles for Service Accounts (IRSA) on Amazon EKS clusters.
4+
5+
## Overview
6+
7+
IRSA allows Kubernetes pods to assume AWS IAM roles without storing long-lived AWS credentials. This is the recommended approach for granting AWS permissions to SpiceDB when running on EKS, as it:
8+
9+
- Eliminates the need to store AWS credentials in secrets
10+
- Provides automatic credential rotation
11+
- Enables fine-grained access control per service account
12+
- Follows AWS security best practices
13+
14+
The `extraServiceAccountAnnotations` field in the SpiceDBCluster spec allows you to add annotations to the ServiceAccount created by the operator, which is required for IRSA to work.
15+
16+
## Prerequisites
17+
18+
1. **EKS Cluster with OIDC Provider**: Your EKS cluster must have an OIDC provider associated with it.
19+
20+
```bash
21+
eksctl utils associate-iam-oidc-provider --cluster <cluster-name> --approve
22+
```
23+
24+
2. **Create an IAM Role**: Create an IAM role with the necessary permissions (e.g., `rds-db:connect` for RDS IAM authentication).
25+
26+
3. **Configure Trust Relationship**: Update the role's trust policy to allow the SpiceDB service account to assume it:
27+
28+
```json
29+
{
30+
"Version": "2012-10-17",
31+
"Statement": [
32+
{
33+
"Effect": "Allow",
34+
"Principal": {
35+
"Federated": "arn:aws:iam::123456789012:oidc-provider/oidc.eks.region.amazonaws.com/id/EXAMPLED539D4633E53DE1B716D3041E"
36+
},
37+
"Action": "sts:AssumeRoleWithWebIdentity",
38+
"Condition": {
39+
"StringEquals": {
40+
"oidc.eks.region.amazonaws.com/id/EXAMPLED539D4633E53DE1B716D3041E:sub": "system:serviceaccount:default:spicedb-with-irsa",
41+
"oidc.eks.region.amazonaws.com/id/EXAMPLED539D4633E53DE1B716D3041E:aud": "sts.amazonaws.com"
42+
}
43+
}
44+
}
45+
]
46+
}
47+
```
48+
49+
> **Note**: The service account name in the trust policy (`spicedb-with-irsa`) must match the SpiceDBCluster name. If you use a custom `serviceAccountName` in your config, use that name instead.
50+
51+
## Configuration
52+
53+
### Basic IRSA Setup
54+
55+
The key configuration is adding the `eks.amazonaws.com/role-arn` annotation to the service account:
56+
57+
```yaml
58+
apiVersion: authzed.com/v1alpha1
59+
kind: SpiceDBCluster
60+
metadata:
61+
name: spicedb-with-irsa
62+
spec:
63+
config:
64+
datastoreEngine: postgres
65+
extraServiceAccountAnnotations:
66+
eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/your-iam-role"
67+
secretName: spicedb-config
68+
```
69+
70+
### Custom Service Account Name
71+
72+
You can specify a custom service account name using the `serviceAccountName` field:
73+
74+
```yaml
75+
spec:
76+
config:
77+
serviceAccountName: "my-custom-sa"
78+
extraServiceAccountAnnotations:
79+
eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/your-iam-role"
80+
```
81+
82+
> **Important**: If you use a custom service account name, update your IAM trust policy to reference `system:serviceaccount:<namespace>:<serviceAccountName>`.
83+
84+
## Use Case: RDS with IAM Authentication
85+
86+
Instead of storing database passwords, you can use IAM authentication with RDS. This requires:
87+
88+
1. The `eks.amazonaws.com/role-arn` annotation for IRSA
89+
2. The `datastoreCredentialsProviderName` config set to `aws-iam`
90+
91+
```yaml
92+
apiVersion: authzed.com/v1alpha1
93+
kind: SpiceDBCluster
94+
metadata:
95+
name: spicedb-with-irsa
96+
namespace: default
97+
spec:
98+
config:
99+
datastoreEngine: postgres
100+
# Enable AWS IAM credential provider for RDS authentication
101+
datastoreCredentialsProviderName: "aws-iam"
102+
extraServiceAccountAnnotations:
103+
eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/spicedb-rds-role"
104+
secretName: spicedb-config
105+
---
106+
apiVersion: v1
107+
kind: Secret
108+
metadata:
109+
name: spicedb-config
110+
namespace: default
111+
stringData:
112+
preshared_key: "your-very-secret-preshared-key"
113+
# Note: No password in the URI - IAM authentication handles this
114+
datastore_uri: "postgresql://spicedb_user@your-rds-endpoint.region.rds.amazonaws.com:5432/spicedb?sslmode=require"
115+
```
116+
117+
### IAM Policy for RDS Access
118+
119+
Your IAM role needs the `rds-db:connect` permission:
120+
121+
```json
122+
{
123+
"Version": "2012-10-17",
124+
"Statement": [
125+
{
126+
"Effect": "Allow",
127+
"Action": "rds-db:connect",
128+
"Resource": "arn:aws:rds-db:region:123456789012:dbuser:db-instance-resource-id/spicedb_user"
129+
}
130+
]
131+
}
132+
```
133+
134+
## Deploying the Example
135+
136+
1. Update the IAM role ARN in `spicedb-with-iam-role.yaml` with your actual role ARN
137+
2. Update the RDS endpoint and database user in the secret
138+
3. Apply the configuration:
139+
140+
```bash
141+
kubectl apply -k .
142+
```
143+
144+
4. Verify the service account has the correct annotation:
145+
146+
```bash
147+
kubectl get sa spicedb-with-irsa -o jsonpath='{.metadata.annotations}'
148+
```
149+
150+
## Troubleshooting
151+
152+
1. **Check Service Account Annotations**:
153+
154+
```bash
155+
kubectl get sa spicedb-with-irsa -o jsonpath='{.metadata.annotations}'
156+
```
157+
158+
2. **Verify Pod Has AWS Environment Variables**:
159+
160+
```bash
161+
kubectl exec -it <spicedb-pod> -- env | grep AWS
162+
```
163+
164+
You should see:
165+
- `AWS_ROLE_ARN`
166+
- `AWS_WEB_IDENTITY_TOKEN_FILE`
167+
168+
3. **Check IAM Role Trust Policy**: Ensure the trust policy matches your cluster's OIDC provider and service account name (including namespace).
169+
170+
4. **Verify RDS IAM Authentication is Enabled**: Ensure your RDS instance has IAM authentication enabled in the AWS console or via CLI.
171+
172+
5. **Check SpiceDB Logs for Auth Errors**:
173+
174+
```bash
175+
kubectl logs -l app.kubernetes.io/instance=spicedb-with-irsa
176+
```
177+
178+
## Additional Resources
179+
180+
- [AWS Documentation on IRSA](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html)
181+
- [SpiceDB Operator Documentation](https://github.com/authzed/spicedb-operator)
182+
- [Using IAM authentication with RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html)
183+
- [Creating an IAM policy for RDS IAM authentication](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.IAMPolicy.html)

‎examples/aws-iam-service-account/kustomization.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
apiVersion: kustomize.config.k8s.io/v1beta1
2+
kind: Kustomization
3+
4+
resources:
5+
- spicedb-with-iam-role.yaml

0 commit comments

Comments
 (0)