https://github.com/controlplane-com/promotion-demo
https://github.com/controlplane-com/promotion-demo
Last synced: 11 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/controlplane-com/promotion-demo
- Owner: controlplane-com
- Created: 2022-03-04T01:27:21.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-03-27T22:44:22.000Z (about 2 years ago)
- Last Synced: 2025-06-09T15:04:58.994Z (about 1 year ago)
- Language: JavaScript
- Size: 30.3 KB
- Stars: 0
- Watchers: 3
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Control Plane - Environment Promotion Example
This example project demonstrates CI/CD for releasing an app to multiple environments. Upon the creation of a pull request, a 'Review Workload' is deployed to a specified "Dev Org". It is prefixed by the branch name. In this manner, multiple branches can be worked on simultaneously. Whenever a pull request is merged, the app is deployed to the same environment with a dev- prefix.
An image is only built once. A short hash is added to the image name to ensure uniqueness. That same image is then deployed to all environments, depending on the action being executed.
While this example utilizes two orgs, it illustrates there's no limitation to the number of orgs you can use.
## GitHub Actions
This project contains three GitHub Actions (in the `./.github/workflows` directory):
1. Before making code changes, create a new branch and perform any changes in the new branch. When ready to deploy a review workload, simply create a pull request to the main branch. On a pull request (or updates to an existing pull request) to the `main` branch, the application is containerized and pushed to the dev Org's private repository. The GVC and `Review Workload` is created (if it not already created) by applying the YAML contents of the files `./cpln/cpln-gvc.yaml` and `./cpln/cpln-workload.yaml`. The name of the `Review Workload` is prefixed by the name of the branch that created the pull request and a dash.
2. When a pull request is accepted and the code is merged into the `main` branch, a `dev` workload is
updated (or created if it doesn't exists) in the dev Org by applying the same files as step 1, except that the workload name is prefixed with `dev-`. This allows the application to be reviewed and tested before being pushed to the production Org.
3. The promotion to the `stage` and `prod` workload is accomplished by manually executing the `Deploy-To-Stage-or-Prod`
workflow and selecting the desired workload type (stage or prod). The target GVC and Workload in the production Org is updated (or created if it doesn't exist) by applying the YAML contents of the files `./cpln/cpln-gvc-prod.yaml` and `./cpln/cpln-workload.yaml`. The main difference between the two GVC files is that the `prod` version contains the `Pull Secret` that is needed the pull the image from the dev Org. The `stage` and `prod` Workloads reuse the image that was initially pushed to the development Org.
## Release Phase
Each action contains a release phase that will execute a script named `release-tasks.sh` within the path
`release/ENVIRONMENT_NAME`. If this phase fails, the remainder of the action will not execute.
## Control Plane Prerequisites
The following Control Plane resources are required:
- Two Control Plane Orgs representing a `dev` and `prod` environments. The `dev` org will host the review and dev Workloads. The `prod` org will host the stage and prod Workloads.
Note: The `stage` and `prod` Workloads are deployed to the `prod` org since these environments should mirror each other.
## Control Plane Authentication Set Up
This example uses the Control Plane CLI to perform the necessary actions within the GitHub Actions. The CLI requires a `Service Account` with the proper permissions to perform actions.
Since actions will be performed against multiple Orgs, a `Service Account` is required in each Org.
**Perform the following steps in each Org:**
1. Follow the Control Plane documentation to create a `Service Account` and create a key. Take a note of the key. It will be used in the next section.
2. Add the Service Account to the `superusers` group. Once the GitHub Action executes as expected, a policy can be created with a limited set of permissions and the `Service Account` can be removed from the `superusers` group.
## Example Set Up
**Perform the following steps to set up the example:**
1. Fork this repo to your own GitHub account.
2. The following variables are required and must be added as GitHub repository secrets.
Browse to the Secrets page by clicking `Settings` (top menu bar), then `Secrets` (left menu bar), and finally click `Actions`.
Add the following variables:
- `CPLN_ORG_DEVELOPMENT`: Name of the `dev` Control Plane Org.
- `CPLN_ORG_PRODUCTION`: Name of the `prod` Control Plane Org.
- `CPLN_GVC`: GVC Name
- `CPLN_WORKLOAD`: Workload Name
- `CPLN_TOKEN_DEVELOPMENT`: Development Org's Service Account Key from the previous step.
- `CPLN_TOKEN_PRODUCTION`: Production Org's Service Account Key from the previous step.
- `CPLN_IMAGE`: The name of the image that will be deployed to the development Org's private repository. The GitHub Action workflow will append the short SHA of the commit as the image tag.
3. Review the `.github/workflow/*` files. These actions will be triggered as described in the `GitHub Actions` section above.
4. Review the Control Plane YAML files that are located in the `/cpln` directory. No changes are required to execute the example.
- The `cpln-gvc.yaml` file defines the GVC to be created/updated for the `dev` Org.
- The `cpln-gvc-prod.yaml` file defines the Pull Secret and GVC to be created/updated for the `prod` Org.
- The `cpln-workload.yaml` file defines the Workload to be created/updated corresponding to the review/dev/staging/prod Workloads.
5. IMPORTANT: In order for the GitHub Actions to execute, they need to be enabled by clicking the `Actions` tab and clicking the `I understand my workflows, go ahead and enable them` button.
## Running the App
After the GitHub Action has successfully deployed the application, it can be tested by following these steps:
1. Browse to the Control Plane Console (https://console.cpln.io/).
2. If necessary, select a different Org by clicking your profile circle in the upper right corner, click the Org pull-down, and select the target Org.
3. Select the GVC that was set in the `CPLN_GVC` variable.
4. Select the desired Workload.
5. Click the `Open` button. The app will open in a new tab and the output will be displayed.
## Notes
- The `cpln apply` command creates and updates the resources defined within the YAML file. If the name of a resource is changed, `cpln apply` will create a new resource. Any orphaned resources will need to be deleted manually.
- The Control Plane CLI commands use the `CPLN_ORG` and `CPLN_TOKEN` environment variables when needed. There is no need to add the --org or --token flags when executing CLI commands.
- The GVC definition must exists in its own YAML file. The `cpln apply` command executing the file that contains the GVC definition must be executed before any child YAML files (workloads, identities, etc.) are executed.
## Permissions
To control which users have the ability to perform sensitive actions, such as merging a pull request, you can utilize the built-in capabilities of GitHub by creating a custom repository role.
Review these instructions on how to create a role.
## Helper Links
GitHub