From 4e6be8095035ee8ec37e64c7fb72c7d8a63c5c18 Mon Sep 17 00:00:00 2001 From: kkb0318 Date: Fri, 9 Aug 2024 20:32:22 +0900 Subject: [PATCH] fix docs for supporting eks --- README.md | 86 ++++------------------------------------ docs/eks-setup.md | 17 ++++++++ docs/selfhosted-setup.md | 81 +++++++++++++++++++++++++++++++++++++ 3 files changed, 105 insertions(+), 79 deletions(-) create mode 100644 docs/eks-setup.md create mode 100644 docs/selfhosted-setup.md diff --git a/README.md b/README.md index e92d560..6930d56 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![CI](https://github.com/kkb0318/irsa-manager/actions/workflows/ci.yaml/badge.svg)](https://github.com/kkb0318/irsa-manager/actions/workflows/ci.yaml) [![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/irsa-manager)](https://artifacthub.io/packages/search?repo=irsa-manager) -IRSA Manager allows you to easily set up IAM Roles for Service Accounts (IRSA) on non-EKS Kubernetes clusters. +IRSA Manager allows you to easily set up IAM Roles for Service Accounts (IRSA) on both EKS and non-EKS Kubernetes clusters. ![](docs/irsa-manager-overview.png) @@ -19,7 +19,7 @@ For detailed guidelines on how irsa-manager works, please refer to the [**blog p Before you begin, ensure you have the following: -- A running Kubernetes cluster (non-EKS). +- A running Kubernetes cluster. - Helm installed on your local machine. - AWS user credentials with appropriate permissions. - The permissions should allow irsa-manager to call the necessary AWS APIs. You can find all the APIs that irsa-manager calls in the internal/aws/aws.go interfaces. @@ -50,7 +50,7 @@ Before you begin, ensure you have the following: ## Setup -Follow these steps to set up IRSA on your non-EKS cluster: +Follow these steps to set up IRSA on your cluster: 1. Set AWS Secret for IRSA Manager @@ -77,85 +77,13 @@ helm install irsa-manager kkb0318/irsa-manager -n irsa-manager-system --create-n 3. Create an IRSASetup Custom Resource -![](docs/IRSASetup-cr.png) +If you're using self-hosted Kubernetes, follow this setup: -Define and apply an IRSASetup custom resource according to your needs. +[self-hosted setup](./docs/selfhosted-setup.md) -```yaml -apiVersion: irsa-manager.kkb0318.github.io/v1alpha1 -kind: IRSASetup -metadata: - name: irsa-init - namespace: irsa-manager-system -spec: - cleanup: false - discovery: - s3: - region: - bucketName: -``` - -Check the IRSASetup custom resource status to verify whether it is set to true. - -> [!NOTE] -> Please ensure that only one IRSASetup resource is created. - -4. Modify kube-apiserver Settings - -If the IRSASetup status is true, a key file (Name: `irsa-manager-key` , Namespace: `kube-system` ) will be created. This is used for signing tokens in the kubernetes API. -Execute the following commands on the control plane server to save the public and private keys locally for Kubernetes signatures: - -```console -kubectl get secret -n kube-system irsa-manager-key -o jsonpath="{.data.ssh-privatekey}" | base64 --decode | sudo tee /path/to/file.key > /dev/null -kubectl get secret -n kube-system irsa-manager-key -o jsonpath="{.data.ssh-publickey}" | base64 --decode | sudo tee /path/to/file.pub > /dev/null -``` - -> [!NOTE] -> Path: `/path/to/file` can be any path you choose. -> If you use kubeadm, it is recommended to set `/etc/kubernetes/pki/irsa-manager.(key|pub)` - -Then, modify the kube-apiserver settings to include the following parameters: - -- API Audiences - -``` ---api-audiences=sts.amazonaws.com -``` - -- Service Account Issuer - -``` ---service-account-issuer=https://s3-.amazonaws.com/ -``` - -> [!NOTE] -> Add this setting as the first element. -> When this flag is specified multiple times, the first is used to generate tokens and all are used to determine which issuers are accepted. - -- Service Account Key File - -The public key generated previously can be read by the API server. Add the path for this parameter flag: - -``` ---service-account-key-file=/path/to/file.pub -``` - -> [!NOTE] -> If you do not mount /path/to directory, you need to add the volumes field to this path. - -- Service Account Signing Key File - -The private key (oidc-issuer.key) generated previously can be read by the API server. Add the path for this parameter flag: - -``` ---service-account-signing-key-file=/path/to/file.key -``` - -> [!NOTE] -> Overwrite the existing settings. -> If you do not mount /path/to directory, you need to add the volumes field to this path. +If you're using EKS, follow this setup: -For more details, refer to the [Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#serviceaccount-token-volume-projection). +[eks setup](./docs/eks-setup.md) ## How To Use diff --git a/docs/eks-setup.md b/docs/eks-setup.md new file mode 100644 index 0000000..34f6468 --- /dev/null +++ b/docs/eks-setup.md @@ -0,0 +1,17 @@ +## Setup for EKS + +Define and apply an IRSASetup custom resource. + +```yaml +apiVersion: irsa-manager.kkb0318.github.io/v1alpha1 +kind: IRSASetup +metadata: + name: irsa-init + namespace: irsa-manager-system +spec: + mode: eks + cleanup: false + iamOIDCProvider: "oidc.eks..amazonaws.com/id/" +``` + +Check the IRSASetup custom resource status to verify whether it is set to true. diff --git a/docs/selfhosted-setup.md b/docs/selfhosted-setup.md new file mode 100644 index 0000000..ed23b6e --- /dev/null +++ b/docs/selfhosted-setup.md @@ -0,0 +1,81 @@ +## Setup for Self-Hosted + +![](docs/IRSASetup-cr.png) + +### Define and apply an IRSASetup custom resource according to your needs. + +```yaml +apiVersion: irsa-manager.kkb0318.github.io/v1alpha1 +kind: IRSASetup +metadata: + name: irsa-init + namespace: irsa-manager-system +spec: + cleanup: false + discovery: + s3: + region: + bucketName: +``` + +Check the IRSASetup custom resource status to verify whether it is set to true. + +> [!NOTE] +> Please ensure that only one IRSASetup resource is created. + +### Modify kube-apiserver Settings + +If the IRSASetup status is true, a key file (Name: `irsa-manager-key` , Namespace: `kube-system` ) will be created. This is used for signing tokens in the kubernetes API. +Execute the following commands on the control plane server to save the public and private keys locally for Kubernetes signatures: + +```console +kubectl get secret -n kube-system irsa-manager-key -o jsonpath="{.data.ssh-privatekey}" | base64 --decode | sudo tee /path/to/file.key > /dev/null +kubectl get secret -n kube-system irsa-manager-key -o jsonpath="{.data.ssh-publickey}" | base64 --decode | sudo tee /path/to/file.pub > /dev/null +``` + +> [!NOTE] +> Path: `/path/to/file` can be any path you choose. +> If you use kubeadm, it is recommended to set `/etc/kubernetes/pki/irsa-manager.(key|pub)` + +Then, modify the kube-apiserver settings to include the following parameters: + +- API Audiences + +``` +--api-audiences=sts.amazonaws.com +``` + +- Service Account Issuer + +``` +--service-account-issuer=https://s3-.amazonaws.com/ +``` + +> [!NOTE] +> Add this setting as the first element. +> When this flag is specified multiple times, the first is used to generate tokens and all are used to determine which issuers are accepted. + +- Service Account Key File + +The public key generated previously can be read by the API server. Add the path for this parameter flag: + +``` +--service-account-key-file=/path/to/file.pub +``` + +> [!NOTE] +> If you do not mount /path/to directory, you need to add the volumes field to this path. + +- Service Account Signing Key File + +The private key (oidc-issuer.key) generated previously can be read by the API server. Add the path for this parameter flag: + +``` +--service-account-signing-key-file=/path/to/file.key +``` + +> [!NOTE] +> Overwrite the existing settings. +> If you do not mount /path/to directory, you need to add the volumes field to this path. + +For more details, refer to the [Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#serviceaccount-token-volume-projection).