Skip to content

Commit 28acde1

Browse files
ivanauthivanauth
committed
Document extraServiceAccountAnnotations with AWS IRSA example
1 parent 27f03e3 commit 28acde1

4 files changed

Lines changed: 391 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 82 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,10 +80,91 @@ zed --insecure --endpoint=localhost:50051 --token=averysecretpresharedkey schema
8080

8181
## Where To Go From Here
8282

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

87+
## Configuration Options
88+
89+
The `SpiceDBCluster` resource supports various configuration options through the `spec.config` field:
90+
91+
### Service Account Annotations
92+
93+
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.
94+
95+
#### AWS IAM Roles for Service Accounts (IRSA)
96+
97+
```yaml
98+
apiVersion: authzed.com/v1alpha1
99+
kind: SpiceDBCluster
100+
metadata:
101+
name: spicedb-with-irsa
102+
spec:
103+
config:
104+
datastoreEngine: postgres
105+
# Required for RDS IAM authentication
106+
datastoreCredentialsProviderName: "aws-iam"
107+
extraServiceAccountAnnotations:
108+
eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/spicedb-role"
109+
```
110+
111+
See the [AWS IAM Service Account example](examples/aws-iam-service-account/) for a complete guide on using IRSA with SpiceDB.
112+
113+
#### GCP Workload Identity
114+
115+
```yaml
116+
apiVersion: authzed.com/v1alpha1
117+
kind: SpiceDBCluster
118+
metadata:
119+
name: spicedb-with-workload-identity
120+
spec:
121+
config:
122+
datastoreEngine: postgres
123+
extraServiceAccountAnnotations:
124+
iam.gke.io/gcp-service-account: "spicedb@my-project.iam.gserviceaccount.com"
125+
```
126+
127+
#### Azure Workload Identity
128+
129+
```yaml
130+
apiVersion: authzed.com/v1alpha1
131+
kind: SpiceDBCluster
132+
metadata:
133+
name: spicedb-with-azure-wi
134+
spec:
135+
config:
136+
datastoreEngine: postgres
137+
extraServiceAccountAnnotations:
138+
azure.workload.identity/client-id: "<AZURE_CLIENT_ID>"
139+
```
140+
141+
### Custom Service Account Name
142+
143+
You can specify a custom service account name using the `serviceAccountName` field:
144+
145+
```yaml
146+
spec:
147+
config:
148+
serviceAccountName: "my-custom-spicedb-sa"
149+
extraServiceAccountAnnotations:
150+
eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/spicedb-role"
151+
```
152+
153+
### Pod Labels and Annotations
154+
155+
You can also add custom labels and annotations to SpiceDB pods:
156+
157+
```yaml
158+
spec:
159+
config:
160+
extraPodLabels:
161+
environment: "production"
162+
team: "platform"
163+
extraPodAnnotations:
164+
prometheus.io/scrape: "true"
165+
prometheus.io/port: "9090"
166+
```
167+
87168
## Automatic and Suggested Updates
88169

89170
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)