From f05a5703a542470a8bf2697f5bd07bee240031d8 Mon Sep 17 00:00:00 2001 From: Carlos Santana Date: Fri, 25 Jul 2025 19:14:32 +0000 Subject: [PATCH 1/6] update readme order the steps --- README.md | 165 +++++++++++++++++++++++++++++------------------------- 1 file changed, 90 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 2e1ac8c4..4004065e 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ -# CNOE AWS Reference Implementation +# AWS Reference Implementation -This project contains a [CNOE](https://cnoe.io) reference implementation for AWS. This project can bring up an Internal Developer Platform on EKS with all the tools configured and ready to use. It will install addons on an EKS cluster as Argo CD apps using GitOps Bridge App of ApplicationSets pattern. Check out the [Getting Started](#getting-started) guide for installing this solution on an EKS cluster. +This project contains an Internal Developer Platform (IDP) reference implementation for AWS. This project can bring up an IDP on EKS with all the tools configured and ready to use in production. It will install addons on an EKS cluster as Argo CD apps using GitOps Bridge App of ApplicationSets pattern. Check out the [Getting Started](#getting-started) guide for installing this solution on an EKS cluster. > [!NOTE] -> Applications deployed in this repository are not meant or configured for production. +> Applications deployed in this repository is a starting point to get environment into production. ## Architecture Overview @@ -20,6 +20,7 @@ All the addons are helm charts with static values configured in `packages/(When not using Auto Mode) | kube-system | aws-load-balancer-controller | [Permissions](https://github.com/kubernetes-sigs/aws-load-balancer-controller/blob/main/docs/install/iam_policy.json) | -| AWS EBS CSI Controller
(When not using Auto Mode) | kube-system | ebs-csi-controller-sa | [Permissions](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonEBSCSIDriverPolicy.html) | +#### πŸ” Configure AWS Credentials +Configure the AWS CLI with credentials of an IAM role which has access to the EKS cluster. Follow the instructions in the [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html#getting-started-quickstart-new) to configure the AWS CLI. +If the installation steps are being executed on an EC2 instance, ensure that the EC2 IAM instance role has permissions to access the EKS cluster or the AWS CLI is configured as mentioned above. -> [!NOTE] -> **Using Existing EKS Cluster** -> -> The reference implementation can be installed on an existing EKS Cluster only if the above prerequisites are completed. ### Step 2. 🏒 Create GitHub Organization @@ -162,33 +154,67 @@ Argo CD requires `url` and `installationId` of the GitHub app. The `url` is the > [!NOTE] > The rest of the installation process assumes the GitHub apps credentials are available in `private/backstage-github.yaml` and `private/argocd-github.yaml` -### Step 5. βš™οΈ Prepare Environment for Installation -#### πŸ“¦ Install Binaries +#### Step 5. πŸ”’ Create Secrets in AWS Secret Manager -The installation requires the following binaries in the local environment: +The values required for the installation are stored in AWS Secret Manager in two secrets: -+ [**AWS CLI**](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) -+ [**kubectl**](https://kubernetes.io/docs/tasks/tools/) -+ [**yq**](https://mikefarah.gitbook.io/yq/v3.x) -+ [**helm**](https://helm.sh/docs/intro/install/) +1. **cnoe-ref-impl/config:** Stores values from **`config.yaml`** in JSON +2. **cnoe-ref-impl/github-app:** Stores GitHub App credentials with file name as key and content of the file as value from **private** directory. -#### πŸ” Configure AWS Credentials -Configure the AWS CLI with credentials of an IAM role which has access to the EKS cluster. Follow the instructions in the [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html#getting-started-quickstart-new) to configure the AWS CLI. +Run the command below to create new secrets or update the existing secrets if they already exist. -If the installation steps are being executed on an EC2 instance, ensure that the EC2 IAM instance role has permissions to access the EKS cluster or the AWS CLI is configured as mentioned above. +```bash +./scripts/create-config-secrets.sh +``` + +> [!WARNING] +> **DO NOT** move to next steps without completing all the instructions in this step + + +### Step 6. ☸️ Create EKS Cluster + +The reference implementation can be installed on a new EKS cluster which can be created like this: + +```bash +export REPO_ROOT=$(git rev-parse --show-toplevel) +$REPO_ROOT/scripts/create-cluster.sh +``` +You will be prompted to select `eksctl` or `terraform` + +For more details on each type of tools check the corresponding guides: ++ **eksctl**: Follow the [instructions](cluster/eksctl) ++ **terraform**: Follow the [instructions](cluster/terraform/) + +This will create all the prerequisite AWS Resources required for the reference implementation, which includes: + ++ EKS cluster with Auto Mode or Without Auto Mode (Managed Node Group with 4 nodes) ++ Pod Identity Associations for following Addons: + +| Name | Namespace | Service Account Name | Permissions | +| ----- | --------- | -------------------- | ---------- | +| Crossplane | crossplane-system | provider-aws | Admin Permissions but with [permission boundary](cluster/iam-policies/crossplane-permissions-boundry.json) | +| External Secrets | external-secrets | external-secrets | [Permissions](https://external-secrets.io/latest/provider/aws-secrets-manager/#iam-policy) | +| External DNS | external-dns | external-dns | [Permissions](https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/aws/#iam-policy) | +| AWS Load Balancer Controller
(When not using Auto Mode) | kube-system | aws-load-balancer-controller | [Permissions](https://github.com/kubernetes-sigs/aws-load-balancer-controller/blob/main/docs/install/iam_policy.json) | +| AWS EBS CSI Controller
(When not using Auto Mode) | kube-system | ebs-csi-controller-sa | [Permissions](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonEBSCSIDriverPolicy.html) | + +> [!NOTE] +> **Using Existing EKS Cluster** +> +> The reference implementation can be installed on an existing EKS Cluster only if the above prerequisites are completed. -#### βš™οΈ Configure Reference Implementation +#### Step 7. βš™οΈ Configure Reference Implementation -The reference implementation uses **`config.yaml`** file in the repository root directory to configure the installation values. The **`config.yaml`** should be updated with appropriate values before proceeding. Refer to the following table and update all the values appropriately. All the values are required. +The reference implementation uses [config.yaml](config.yaml) file in the repository root directory to configure the installation values. The **`config.yaml`** should be updated with appropriate values before proceeding. Refer to the following table and update all the values appropriately. All the values are required. | Parameter | Description | Type | |-----------|-------------|------| +| `cluster_name` | Name of the EKS cluster for reference implementation
**(The name should satisfy criteria of a valid [kubernetes resource name](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/))** | string | +| `auto_mode` | Set to "true" if EKS cluster is Auto Mode, otherwise "false" | string | | `repo.url` | GitHub URL of the fork in the Github Org | string | | `repo.revision` | Branch or tag which should be used for Argo CD Apps | string | | `repo.basepath` | Directory in which the configuration of addons is stored | string | -| `cluster_name` | Name of the EKS cluster for reference implementation
**(The name should satisfy criteria of a valid [kubernetes resource name](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/))** | string | -| `auto_mode` | Set to "true" if EKS cluster is Auto Mode, otherwise "false" | string | | `region` | AWS Region of the EKS cluster and config secret | string | | `domain` | Base Domain name for exposing services
**(This should be base domain or sub domain of the Route53 Hosted Zone)** | string | | `route53_hosted_zone_id` | Route53 hosted zone ID for configuring external-dns | string | @@ -198,55 +224,22 @@ The reference implementation uses **`config.yaml`** file in the repository root > [!TIP] > If these values are updated after installation, ensure to run the command in the next step to update the values in AWS Secret Manager. Otherwise, the updated values will not reflect in the live installation. -#### πŸ”’ Create Secrets in AWS Secret Manager - -The values required for the installation are stored in AWS Secret Manager in two secrets: - -1. **cnoe-ref-impl/config:** Stores values from **`config.yaml`** in JSON -2. **cnoe-ref-impl/github-app:** Stores GitHub App credentials with file name as key and content of the file as value from **private** directory. - -Run the command below to create new secrets or update the existing secrets if they already exist. - -```bash -./scripts/create-config-secrets.sh -``` - -> [!WARNING] -> **DO NOT** move to next steps without completing all the instructions in this step - -### Step 6. πŸš€ Installation +### Step 8. πŸš€ Deployment > [!NOTE] > Before moving forward, ensure that the kubectl context is set to the EKS cluster and the configured AWS IAM role has access to the cluster. #### ▢️ Start the Installation Process All the addons are installed as Argo CD apps. At the start of the installation, Argo CD and External Secret Operator are installed on the EKS cluster as a helm chart. Once Argo CD on EKS is up, other addons are installed through it and finally the Argo CD on EKS also manages itself and External Secret Operator. Check out more details about the [installation flow](docs/installation_flow.md). Run the following command to start the installation. - ```bash - scripts/install.sh - ``` - -#### πŸ“Š Monitor Installation Process - -The installation script will continue to run until all the Argo CD apps for addons are healthy. To monitor the process, use the instructions below to access the instance of Argo CD running on EKS. - -Check if the kubectl context is set to the EKS cluster and it can access the EKS cluster. Then, start the kubernetes port-forward session for the Argo CD service and access the Argo CD UI in a browser. In the Argo CD UI, monitor the health of all Argo CD Apps - - ```bash - kubectl port-forward -n argocd svc/argocd-server 8080:80 - ``` - -Depending upon the configuration, Argo CD will be accessible at http://localhost:8080 or http://localhost:8080/argocd. - -The credentials for Argo CD can be retrieved with the following command: ```bash -kubectl get secrets -n argocd argocd-initial-admin-secret -oyaml | yq '.data.password' | base64 -d && echo +scripts/install.sh ``` -### Step 7. 🌐 Accessing the Platform +### Step 9. 🌐 Accessing the Platform The addons with Web UI are exposed using the base domain configured in [Step 5](#️-configure-reference-implementation). The URLs can be retrieved by running the following command: -``` +```bash scripts/get-urls.sh ``` The URL depends on the setting for `path_routing`. Refer to following table for URLs: @@ -257,6 +250,28 @@ The URL depends on the setting for `path_routing`. Refer to following table for | Argo CD | https://[domain]/argocd | https://argocd.[domain] | | Argo Workflows | https://[domain]/argo-workflows | https://argo-workflows.[domain] | + +#### πŸ“Š Monitor Deployment Process + +The installation script will continue to run until all the Argo CD apps for addons are healthy. To monitor the process, use the instructions below to access the instance of Argo CD running on EKS. + +Check if the kubectl context is set to the EKS cluster and it can access the EKS cluster. + +You can use `kubectl` to check the status of the Argo CD applications + +```bash +kubectl get applications -n argocd --watch +``` + +Get the credentials for Argo CD and start a port-forward with this command: + +```bash +kubectl get secrets -n argocd argocd-initial-admin-secret -oyaml | yq '.data.password' | base64 -d && echo +kubectl port-forward -n argocd svc/argocd-server 8080:80 +``` + +Depending upon the configuration, Argo CD will be accessible at http://localhost:8080 or http://localhost:8080/argocd. + All the addons are configured with Keycloak SSO USER1 and the user password for it can be retrieved using the following command: ```bash @@ -271,12 +286,12 @@ For troubleshooting, refer to the [troubleshooting guide](docs/troubleshooting.m Run the following command to remove all the addons created by this installation: -``` +```bash scripts/uninstall.sh ``` This script will only remove resources other than CRDs from the EKS cluster so that the same cluster can be used for re-installation which is useful during development. To remove CRDs, use the following command: -``` +```bash scripts/cleanup-crds.sh ``` From ccd1a3f5573d410d100ff7b79caeb2cb34acf0d6 Mon Sep 17 00:00:00 2001 From: Carlos Santana Date: Fri, 25 Jul 2025 15:16:06 -0400 Subject: [PATCH 2/6] Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4004065e..7b44c49c 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ This project contains an Internal Developer Platform (IDP) reference implementation for AWS. This project can bring up an IDP on EKS with all the tools configured and ready to use in production. It will install addons on an EKS cluster as Argo CD apps using GitOps Bridge App of ApplicationSets pattern. Check out the [Getting Started](#getting-started) guide for installing this solution on an EKS cluster. > [!NOTE] -> Applications deployed in this repository is a starting point to get environment into production. +> Applications deployed in this repository are a starting point to get environment into production. ## Architecture Overview From 725e3b945b6860a6b34e7bf3e0c6117626060ba4 Mon Sep 17 00:00:00 2001 From: Carlos Santana Date: Fri, 25 Jul 2025 15:16:14 -0400 Subject: [PATCH 3/6] Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7b44c49c..10352378 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ All the addons are helm charts with static values configured in `packages/ Date: Fri, 25 Jul 2025 19:19:14 +0000 Subject: [PATCH 4/6] fix user1 Signed-off-by: Carlos Santana --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 10352378..0047ec73 100644 --- a/README.md +++ b/README.md @@ -272,7 +272,7 @@ kubectl port-forward -n argocd svc/argocd-server 8080:80 Depending upon the configuration, Argo CD will be accessible at http://localhost:8080 or http://localhost:8080/argocd. -All the addons are configured with Keycloak SSO USER1 and the user password for it can be retrieved using the following command: +All the addons are configured with Keycloak SSO `user1` and the user password for it can be retrieved using the following command: ```bash kubectl get secret -n keycloak keycloak-config -o jsonpath='{.data.USER1_PASSWORD}' | base64 -d && echo From 99da7b2e0db30fa906def9e8f6920dbc295ed2f5 Mon Sep 17 00:00:00 2001 From: Carlos Santana Date: Fri, 25 Jul 2025 19:24:36 +0000 Subject: [PATCH 5/6] move create secret down Signed-off-by: Carlos Santana --- README.md | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 0047ec73..5163ee9b 100644 --- a/README.md +++ b/README.md @@ -155,24 +155,7 @@ Argo CD requires `url` and `installationId` of the GitHub app. The `url` is the > The rest of the installation process assumes the GitHub apps credentials are available in `private/backstage-github.yaml` and `private/argocd-github.yaml` -#### Step 5. πŸ”’ Create Secrets in AWS Secret Manager - -The values required for the installation are stored in AWS Secret Manager in two secrets: - -1. **cnoe-ref-impl/config:** Stores values from **`config.yaml`** in JSON -2. **cnoe-ref-impl/github-app:** Stores GitHub App credentials with file name as key and content of the file as value from **private** directory. - -Run the command below to create new secrets or update the existing secrets if they already exist. - -```bash -./scripts/create-config-secrets.sh -``` - -> [!WARNING] -> **DO NOT** move to next steps without completing all the instructions in this step - - -### Step 6. ☸️ Create EKS Cluster +### Step 5. ☸️ Create EKS Cluster The reference implementation can be installed on a new EKS cluster which can be created like this: @@ -204,7 +187,7 @@ This will create all the prerequisite AWS Resources required for the reference i > > The reference implementation can be installed on an existing EKS Cluster only if the above prerequisites are completed. -#### Step 7. βš™οΈ Configure Reference Implementation +#### Step 6. βš™οΈ Configure Reference Implementation The reference implementation uses [config.yaml](config.yaml) file in the repository root directory to configure the installation values. The **`config.yaml`** should be updated with appropriate values before proceeding. Refer to the following table and update all the values appropriately. All the values are required. @@ -224,6 +207,24 @@ The reference implementation uses [config.yaml](config.yaml) file in the reposit > [!TIP] > If these values are updated after installation, ensure to run the command in the next step to update the values in AWS Secret Manager. Otherwise, the updated values will not reflect in the live installation. +#### Step 7. πŸ”’ Create Secrets in AWS Secret Manager + +The values required for the installation are stored in AWS Secret Manager in two secrets: + +1. **cnoe-ref-impl/config:** Stores values from **`config.yaml`** in JSON +2. **cnoe-ref-impl/github-app:** Stores GitHub App credentials with file name as key and content of the file as value from **private** directory. + +Run the command below to create new secrets or update the existing secrets if they already exist. + +```bash +./scripts/create-config-secrets.sh +``` + +> [!WARNING] +> **DO NOT** move to next steps without completing all the instructions in this step + + + ### Step 8. πŸš€ Deployment > [!NOTE] > Before moving forward, ensure that the kubectl context is set to the EKS cluster and the configured AWS IAM role has access to the cluster. From 005231363196e6766bd8fccc190ac231a93a0788 Mon Sep 17 00:00:00 2001 From: Carlos Santana Date: Fri, 25 Jul 2025 19:27:29 +0000 Subject: [PATCH 6/6] update order Signed-off-by: Carlos Santana --- README.md | 69 +++++++++++++++++++++++++++---------------------------- 1 file changed, 34 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 5163ee9b..cb6927cc 100644 --- a/README.md +++ b/README.md @@ -154,40 +154,7 @@ Argo CD requires `url` and `installationId` of the GitHub app. The `url` is the > [!NOTE] > The rest of the installation process assumes the GitHub apps credentials are available in `private/backstage-github.yaml` and `private/argocd-github.yaml` - -### Step 5. ☸️ Create EKS Cluster - -The reference implementation can be installed on a new EKS cluster which can be created like this: - -```bash -export REPO_ROOT=$(git rev-parse --show-toplevel) -$REPO_ROOT/scripts/create-cluster.sh -``` -You will be prompted to select `eksctl` or `terraform` - -For more details on each type of tools check the corresponding guides: -+ **eksctl**: Follow the [instructions](cluster/eksctl) -+ **terraform**: Follow the [instructions](cluster/terraform/) - -This will create all the prerequisite AWS Resources required for the reference implementation, which includes: - -+ EKS cluster with Auto Mode or Without Auto Mode (Managed Node Group with 4 nodes) -+ Pod Identity Associations for following Addons: - -| Name | Namespace | Service Account Name | Permissions | -| ----- | --------- | -------------------- | ---------- | -| Crossplane | crossplane-system | provider-aws | Admin Permissions but with [permission boundary](cluster/iam-policies/crossplane-permissions-boundry.json) | -| External Secrets | external-secrets | external-secrets | [Permissions](https://external-secrets.io/latest/provider/aws-secrets-manager/#iam-policy) | -| External DNS | external-dns | external-dns | [Permissions](https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/aws/#iam-policy) | -| AWS Load Balancer Controller
(When not using Auto Mode) | kube-system | aws-load-balancer-controller | [Permissions](https://github.com/kubernetes-sigs/aws-load-balancer-controller/blob/main/docs/install/iam_policy.json) | -| AWS EBS CSI Controller
(When not using Auto Mode) | kube-system | ebs-csi-controller-sa | [Permissions](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonEBSCSIDriverPolicy.html) | - -> [!NOTE] -> **Using Existing EKS Cluster** -> -> The reference implementation can be installed on an existing EKS Cluster only if the above prerequisites are completed. - -#### Step 6. βš™οΈ Configure Reference Implementation +#### Step 5. βš™οΈ Configure Reference Implementation The reference implementation uses [config.yaml](config.yaml) file in the repository root directory to configure the installation values. The **`config.yaml`** should be updated with appropriate values before proceeding. Refer to the following table and update all the values appropriately. All the values are required. @@ -207,7 +174,8 @@ The reference implementation uses [config.yaml](config.yaml) file in the reposit > [!TIP] > If these values are updated after installation, ensure to run the command in the next step to update the values in AWS Secret Manager. Otherwise, the updated values will not reflect in the live installation. -#### Step 7. πŸ”’ Create Secrets in AWS Secret Manager + +#### Step 6. πŸ”’ Create Secrets in AWS Secret Manager The values required for the installation are stored in AWS Secret Manager in two secrets: @@ -223,6 +191,37 @@ Run the command below to create new secrets or update the existing secrets if th > [!WARNING] > **DO NOT** move to next steps without completing all the instructions in this step +### Step 7. ☸️ Create EKS Cluster + +The reference implementation can be installed on a new EKS cluster which can be created like this: + +```bash +export REPO_ROOT=$(git rev-parse --show-toplevel) +$REPO_ROOT/scripts/create-cluster.sh +``` +You will be prompted to select `eksctl` or `terraform` + +For more details on each type of tools check the corresponding guides: ++ **eksctl**: Follow the [instructions](cluster/eksctl) ++ **terraform**: Follow the [instructions](cluster/terraform/) + +This will create all the prerequisite AWS Resources required for the reference implementation, which includes: + ++ EKS cluster with Auto Mode or Without Auto Mode (Managed Node Group with 4 nodes) ++ Pod Identity Associations for following Addons: + +| Name | Namespace | Service Account Name | Permissions | +| ----- | --------- | -------------------- | ---------- | +| Crossplane | crossplane-system | provider-aws | Admin Permissions but with [permission boundary](cluster/iam-policies/crossplane-permissions-boundry.json) | +| External Secrets | external-secrets | external-secrets | [Permissions](https://external-secrets.io/latest/provider/aws-secrets-manager/#iam-policy) | +| External DNS | external-dns | external-dns | [Permissions](https://kubernetes-sigs.github.io/external-dns/latest/docs/tutorials/aws/#iam-policy) | +| AWS Load Balancer Controller
(When not using Auto Mode) | kube-system | aws-load-balancer-controller | [Permissions](https://github.com/kubernetes-sigs/aws-load-balancer-controller/blob/main/docs/install/iam_policy.json) | +| AWS EBS CSI Controller
(When not using Auto Mode) | kube-system | ebs-csi-controller-sa | [Permissions](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonEBSCSIDriverPolicy.html) | + +> [!NOTE] +> **Using Existing EKS Cluster** +> +> The reference implementation can be installed on an existing EKS Cluster only if the above prerequisites are completed. ### Step 8. πŸš€ Deployment