fix readme

README.md

@@ -29,6 +29,9 @@ helm repo update
 helm install irsa-manager kkb0318/irsa-manager -n irsa-manager-system --create-namespace
 ```
 
+> [!NOTE]
+> You may encounter an error during the deployment. Proceed with the following steps and create the "aws-secret" secret to eliminate the error.
+
 2. Set AWS Secret for IRSA Manager
 
 Create a secret for irsa-manager to access AWS:
@@ -46,6 +49,21 @@ kubectl create secret generic aws-secret -n irsa-manager-system \
 
 Define and apply an IRSASetup custom resource according to your needs.
 
+```
+apiVersion: irsa.kkb0318.github.io/v1alpha1
+kind: IRSASetup
+metadata:
+  name: irsa-init
+  namespace: irsa-manager-system
+spec:
+  cleanup: false
+  mode: selfhosted
+  discovery:
+    s3:
+      region: <region>
+      bucketName: <S3 bucket name>
+```
+
 4. Modify kube-apiserver Settings
 
 Execute the following commands on the control plane server to save the public and private keys for Kubernetes signatures:
@@ -66,7 +84,7 @@ Then, modify the kube-apiserver.yaml file to include the following parameters:
 - Service Account Issuer
 
 ```
---service-account-issuer=https://s3-<region>.amazonaws.com/<bucketName>
+--service-account-issuer=https://s3-<region>.amazonaws.com/<S3 bucket name>
 ```
 
 - Service Account Key File
@@ -89,25 +107,68 @@ The private key (oidc-issuer.key) generated previously can be read by the API se
 ```
 
 > [!NOTE]
-> Add these settings before the existing ones. If specified multiple times, tokens signed by any of the specified keys are considered valid by the Kubernetes API server.
+> Overwrite the existing settings.
 
 For more details, refer to the [Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#serviceaccount-token-volume-projection).
 
-TODO
+5. Check the status
 
-- [x] delete secret
+Check the IRSASetup custom resource status. If the status is true, you are ready to use IRSA.
-- [x] delete s3
-- [x] only once secret creation (status check)
-- [x] no update secret
-- [x] no update bucket object
-- [x] delete idp
-- [x] issue: when irsasetup was deleted, resource remained with some error occured
-- [x] certificate
-- [x] check keys.json keyid has to be empty or not
-- [x] IRSA api
-- [ ] use with cert-manager
-- [ ] aws context
-- [ ] temporary aws account
-- [ ] cannot delete IRSASetup before existing IRSA
 
-- [ ] validation webhook (invalid to change)
+## How To Use
+
+You can set IRSA for the Kubernetes ServiceAccount.
+
+The following example shows that irsa-manager sets the `irsa1-sa` ServiceAccount in the kube-system and default namespaces with the AmazonS3FullAccess policy:
+
+```
+apiVersion: irsa.kkb0318.github.io/v1alpha1
+kind: IRSA
+metadata:
+  name: irsa-sample
+  namespace: irsa-manager-system
+spec:
+  cleanup: true
+  serviceAccount:
+    name: irsa1-sa
+    namespaces:
+      - kube-system
+      - default
+  iamRole:
+    name: irsa1-role
+  iamPolicies:
+    - AmazonS3FullAccess
+```
+
+For more details, please see the API Reference.
+
+## Verification
+
+To verify the above example and ensure the IRSA works correctly, you can check the following job.
+There is a Kubernetes job that will put one file into the S3 bucket, confirming that the Pod can assume the role to get S3 write permission:
+
+```
+cd validation
+sh s3-echoer.sh
+```
+
+## API Reference
+
+You can find the reference in the [Reference](./docs/api.md) file.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
+
+## Acknowledgments
+
+In creating this OSS project, I referred to several sources and would like to express my gratitude for their valuable information and insights.
+
+The necessity of this project was realized through discussions in the following issue:
+
+- https://github.com/kubernetes-sigs/cluster-api-provider-aws/issues/3560
+
+Additionally, the implementation was guided by the following repositories:
+
+- [smalltown/aws-irsa-example](https://github.com/smalltown/aws-irsa-example)
+- [aws/amazon-eks-pod-identity-webhook](https://github.com/aws/amazon-eks-pod-identity-webhook)

config/manager/manager.yaml

@@ -77,25 +77,25 @@ spec:
                 secretKeyRef:
                   name: aws-secret
                   key: aws-access-key-id
-                  optional: true
+                  # optional: true
             - name: AWS_SECRET_ACCESS_KEY
               valueFrom:
                 secretKeyRef:
                   name: aws-secret
                   key: aws-secret-access-key
-                  optional: true
+                  # optional: true
             - name: AWS_REGION
               valueFrom:
                 secretKeyRef:
                   name: aws-secret
                   key: aws-region
-                  optional: true
+                  # optional: true
             - name: AWS_ROLE_ARN
               valueFrom:
                 secretKeyRef:
                   name: aws-secret
                   key: aws-role-arn
-                  optional: true
+                  # optional: true
           name: manager
           securityContext:
             allowPrivilegeEscalation: false

examples/selfhosted.yaml

@@ -9,4 +9,4 @@ spec:
   discovery:
     s3:
       region: ap-northeast-1
-      bucketName: irsa-manager-test-kkb0010101
+      bucketName: irsa-manager-test-f4vhae

validation/job-amd.yaml.template

@@ -0,0 +1,21 @@
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: s3-echoer
+spec:
+  template:
+    spec:
+      serviceAccountName: s3-echoer
+      containers:
+        - name: main
+          image: amazonlinux:2018.03
+          command:
+            - "sh"
+            - "-c"
+            - "curl -sL -o /s3-echoer https://github.com/mhausenblas/s3-echoer/releases/latest/download/s3-echoer-linux && chmod +x /s3-echoer && echo This is an in-cluster test | /s3-echoer TARGET_BUCKET"
+          env:
+            - name: AWS_DEFAULT_REGION
+              value: "ap-northeast-1"
+            - name: ENABLE_IRP
+              value: "true"
+      restartPolicy: Never

validation/job-arm.yaml.template

@@ -0,0 +1,21 @@
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: s3-echoer
+spec:
+  template:
+    spec:
+      serviceAccountName: s3-echoer
+      containers:
+        - name: main
+          image: amazonlinux:2023
+          command:
+            - "sh"
+            - "-c"
+            - "curl -sL -o /s3-echoer https://github.com/kkb0318/s3-echoer-arm/releases/latest/download/s3-echoer-linux-arm64 && chmod +x /s3-echoer && echo This is an in-cluster test | /s3-echoer TARGET_BUCKET"
+          env:
+            - name: AWS_DEFAULT_REGION
+              value: "ap-northeast-1"
+            - name: ENABLE_IRP
+              value: "true"
+      restartPolicy: Never

validation/s3-echoer.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+
+TARGET_BUCKET_PREFIX=s3-echoer
+AWS_DEFAULT_REGION=${AWS_DEFAULT_REGION:-ap-northeast-1}
+JOB_TEMPLATE=job-arm.yaml.template
+
+# deploy s3 echoer job into k8s cluster
+timestamp=$(date +%s)
+TARGET_BUCKET=$ROLE_NAME-$timestamp
+
+aws s3api create-bucket \
+          --bucket $TARGET_BUCKET_PREFIX \
+          --create-bucket-configuration LocationConstraint=$AWS_DEFAULT_REGION \
+          --region $AWS_DEFAULT_REGION
+
+sed -e "s/TARGET_BUCKET/${TARGET_BUCKET_PREFIX}/g" ${JOB_TEMPLATE} > s3-echoer-job.yaml
+
+kubectl create -f s3-echoer-job.yaml
+
+echo "The S3 bucket is $TARGET_BUCKET_PREFIX"
+