Add Python IRSA example for managing AWS ECR repositories

Signed-off-by: Han Verstraete (OpenFaaS Ltd) <han@openfaas.com>

Author: welteki

docs/languages/python.md

@@ -586,6 +586,187 @@ curl -X POST http://127.0.0.1:8080/function/s3-example?key=hello.txt \
 curl http://127.0.0.1:8080/function/s3-example
 ```
 
+## Example: Manage AWS ECR repositories with IRSA
+
+This example is for OpenFaaS deployed on [AWS EKS](https://aws.amazon.com/eks/). It shows how to use the `boto3` SDK with [IAM Roles for Service Accounts (IRSA)](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) to manage AWS ECR repositories from a Python function. Instead of storing static AWS credentials as secrets, the function obtains ambient credentials automatically from a Kubernetes Service Account that is mapped to an IAM role.
+
+IRSA is the recommended way to handle AWS credentials for functions running on EKS. It avoids long-lived static credentials that need to be manually rotated, and follows the principle of least privilege by scoping permissions to individual functions through IAM roles.
+
+IRSA must be enabled on your EKS cluster. This requires an IAM OIDC identity provider associated with the cluster. See [Creating an IAM OIDC provider for your cluster](https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html) for setup instructions. For a more detailed end-to-end walkthrough, see: [Manage AWS Resources from OpenFaaS Functions With IRSA](https://www.openfaas.com/blog/irsa-functions/).
+
+**1. Create an IAM Policy**
+
+Create a policy that grants the permissions your function needs. This example creates and queries ECR repositories:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "ecr:CreateRepository",
+        "ecr:DeleteRepository",
+        "ecr:DescribeRepositories"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+Save the above to `ecr-policy.json` and create the policy:
+
+```bash
+aws iam create-policy \
+  --policy-name ecr-create-query-repository \
+  --policy-document file://ecr-policy.json
+```
+
+Note the ARN from the output, e.g. `arn:aws:iam::ACCOUNT_NUMBER:policy/ecr-create-query-repository`.
+
+**2. Create an IAM Role and Kubernetes Service Account**
+
+Use `eksctl` to create a Kubernetes Service Account in the `openfaas-fn` namespace that is linked to an IAM role with the policy attached:
+
+```bash
+export ARN=arn:aws:iam::ACCOUNT_NUMBER:policy/ecr-create-query-repository
+
+eksctl create iamserviceaccount \
+  --name openfaas-create-ecr-repo \
+  --namespace openfaas-fn \
+  --cluster <cluster-name> \
+  --role-name ecr-create-query-repository \
+  --attach-policy-arn $ARN \
+  --region eu-west-1 \
+  --approve
+```
+
+This can also be done manually by creating the IAM Role in AWS, followed by a Kubernetes Service Account annotated with `eks.amazonaws.com/role-arn`.
+
+**3. Create the function**
+
+Pull the `python3-http-debian` template and scaffold a new function:
+
+```bash
+faas-cli template store pull python3-http-debian
+faas-cli new --lang python3-http-debian ecr-create-repo \
+  --prefix ttl.sh/openfaas-examples
+```
+
+**4. Add the boto3 dependency**
+
+Add `boto3` to the function's `requirements.txt`:
+
+```
+boto3
+```
+
+**5. Configure the function**
+
+Update `stack.yaml` to set the AWS region and assign the Kubernetes Service Account created for IRSA. The `com.openfaas.serviceaccount` annotation tells OpenFaaS which service account to attach to the function's pod:
+
+```yaml
+functions:
+  ecr-create-repo:
+    lang: python3-http-debian
+    handler: ./ecr-create-repo
+    image: ttl.sh/openfaas-examples/ecr-create-repo:latest
+    annotations:
+      com.openfaas.serviceaccount: openfaas-create-ecr-repo
+    environment:
+      AWS_REGION: eu-west-1
+```
+
+No secrets are needed — the AWS SDK picks up credentials automatically from the service account token that is mounted into the pod by EKS.
+
+**6. Write the handler**
+
+The handler uses `boto3` to create ECR repositories. The `boto3` session is initialised once and reused across invocations. Because IRSA is configured, the SDK automatically obtains temporary credentials from the service account token without any explicit credential management.
+
+```python
+import os
+import json
+import boto3
+
+ecrClient = None
+
+def initECR():
+    session = boto3.Session(
+        region_name=os.getenv('AWS_REGION'),
+    )
+    return session.client('ecr')
+
+def handle(event, context):
+    global ecrClient
+
+    if ecrClient is None:
+        ecrClient = initECR()
+
+    if event.method != 'POST':
+        return {
+            "statusCode": 405,
+            "body": "Method not allowed"
+        }
+
+    body = json.loads(event.body)
+    name = body.get('name')
+
+    if not name:
+        return {
+            "statusCode": 400,
+            "body": "Missing in body: name"
+        }
+
+    # Check if the repository already exists
+    try:
+        ecrClient.describe_repositories(repositoryNames=[name])
+        return {
+            "statusCode": 200,
+            "body": json.dumps({"message": "Repository already exists"})
+        }
+    except ecrClient.exceptions.RepositoryNotFoundException:
+        pass
+
+    # Create the repository
+    response = ecrClient.create_repository(
+        repositoryName=name,
+        imageTagMutability='MUTABLE',
+        encryptionConfiguration={
+            'encryptionType': 'AES256',
+        },
+        imageScanningConfiguration={
+            'scanOnPush': False,
+        },
+    )
+
+    return {
+        "statusCode": 201,
+        "body": json.dumps({
+            "arn": response['repository']['repositoryArn']
+        })
+    }
+```
+
+**7. Deploy and invoke**
+
+```bash
+faas-cli up \
+ --filter ecr-create-repo \
+ --tag digest
+
+# Create a new ECR repository
+curl -X POST http://127.0.0.1:8080/function/ecr-create-repo \
+  -H "Content-Type: application/json" \
+  -d '{"name":"tenant1/fn1"}'
+```
+
+The response contains the ARN of the newly created repository:
+
+```json
+{"arn": "arn:aws:ecr:eu-west-1:ACCOUNT_NUMBER:repository/tenant1/fn1"}
+```
+
 ## Example: Publish messages to Kafka
 
 This example shows how to produce messages to a Kafka topic from a Python function using the `confluent-kafka` package with SASL/SSL authentication.