Deploy Kubernetes
Introduction
This page details the instructions for deployment of Cinchy on Kubernetes. We recommend, and have documented below, that this is done via Terraform and ArgoCD. This setup involves a utility to centralize and streamline your configurations.
The Terraform scripts and instructions provided enable deployment on Azure and AWS cloud environments.
Deployment prerequisites
To install Cinchy v5 on Kubernetes, you need to follow the requirements below.
Common prerequisites
Whether installing on Azure or AWS, these common prerequisites are essential:
Git repository setup
- Create four Git repositories on any Git-supporting platform like
GitLab,
Azure DevOps,
or GitHub. These include:
cinchy.terraform
: For Terraform configurations.cinchy.argocd
: For ArgoCD configurations.cinchy.kubernetes
: For cluster and application deployment manifests.cinchy.devops.automations
: For maintaining the contents of the above repositories.
Repository artifacts
- Download and check in the artifacts for these repositories. Accessing Cinchy Artifacts.
- Ensure a service account with read/write permissions to these repositories.
Tools
- Install these tools on your deployment machine:
- Terraform
- AWS: Get Started Guide
- Azure: Get Started Guide
- kubectl (v1.23.0+)
- .NET Core 3.1.x
- Bash (Windows:
- Git Bash)
- cksctl CLI]
- Terraform
Docker images
- For using Cinchy docker images, pull them here.
- From Cinchy v5.4, choose between Alpine or Debian image tags:
"5.x.x"
- Alpine"5.x.x-debian"
- Debian (select for DB2 data sync)
Domain and SSL Certificate
- A single domain is required for accessing various applications.
- Choose between path-based or subdomain-based routing.
- Ensure an SSL certificate for the cluster (wildcard recommended for subdomain routing). Self-Signed SSL Option
Sample routing options
See below for routing options for multiple instances.
Application | Path Based Routing | Subdomain Based Routing |
---|---|---|
Cinchy 1 (DEV) | domain.com/dev | dev.mydomain.com |
Cinchy 2 (QA) | domain.com/qa | qa.mydomain.com |
Cinchy 3 (UAT) | domain.com/uat | uat.mydomain.com |
ArgoCD | domain.com/argocd | cluster.mydomain.com/argocd |
Grafana | domain.com/grafana | cluster.mydomain.com/grafana |
OpenSearch | domain.com/dashboard | cluster.mydomain.com/dashboard |
- AWS
- Azure
AWS requirements for Cinchy v5
Terraform Requirements
- S3 Bucket: Set up an S3 bucket to store the Terraform state.
- AWS CLI: Install the AWS CLI on the deployment machine and configure it with the correct profile.
VPC Options
Using an existing VPC
- VPC Setup: Ensure the VPC has a suitable range, like a CIDR with /21 for about 2048 IP addresses.
- Subnets: Create 3 Subnets, one per Availability Zone (AZ), each with sufficient range (e.g., CIDR with /23 for 512 IP addresses).
- NAT Gateway: Required for private subnets to enable node group registration with the EKS cluster.
Creating a new VPC
- Resource Provisioning: All necessary resources will be provisioned automatically.
- vCPU Availability: Verify the "Running On-Demand All Standard" vCPUs limit can support a minimum of 24 vCPUs.
- IAM User Account: Ensure the account has privileges to create resources in any existing VPC or to create a new VPC.
- SSL Certificate: Import an SSL certificate into AWS Certificate Manager, or request a new one via AWS Certificate Manager. For importing, prepare the PEM-encoded certificate body and private key. Learn more about importing certificates.
EKS prerequisite
For AWS, you must intall the eksctl CLI.
EKS prerequisite
For AWS, you must intall the eksctl CLI.
Tips for Success: Ensure consistent region configuration across your SSL Certificate, Terraform bucket, and the deployment.json in the subsequent steps. Tips for Success: Ensure consistent region configuration across your SSL Certificate, Terraform bucket, and the deployment.json in the subsequent steps.
Azure requirements for Cinchy v5
Terraform requirements
- Resource Group: Ensure a resource group for Azure Blob Storage containing the Terraform state.
- Storage Account and Container: Set up Azure Blob Storage for persisting Terraform state.
- Azure CLI: Install the Azure CLI on the deployment machine with the correct profile.
Resource Group Options
Using an existing Resource Group
- Resource Group Setup: Provision the resource group before deployment.
- Virtual Network (VNet): Create a VNet within the resource group.
- Subnet: Establish a single subnet with sufficient range (For example, a CIDR with /22 for 1024 addresses).
Creating a new Resource Group
- Resource Provisioning: All necessary resources will be provisioned automatically.
- vCPU Quota: Check the quota for "Total Regional vCPUs" and "Standard DSv3 Family vCPUs" (or equivalent) to support a minimum of 24 vCPUs.
- AAD User Account: Ensure the account has privileges to create resources in any existing resource groups or to create a new resource group.
Initial configuration
The initial setup involves configuring the deployment.json
file. Follow these
steps:
Configure the deployment.json
File
- Access the Repository: Go to your
cinchy.devops.automations
repository. You'll findaws.json
andazure.json
files there. - Choose the File: Depending on whether you are deploying to AWS or Azure,
select the respective file (
aws.json
orazure.json
). Copy it and rename it todeployment.json
(or<cluster name>.json
) in the same directory. - Edit the Configuration: The
deployment.json
file contains infrastructure resource configurations and settings for Cinchy instances. Each configuration property includes comments describing its purpose and instructions for completion. - Configure and Save: Follow the in-file guidance to adjust the properties.
- Commit Changes: After configuring, commit and push your changes to the repository.
- Revisiting Configuration: You can return to this step anytime during deployment to update configurations. Re-run through the guide sequentially after any changes.
- Handling Credentials: The
deployment.json
requires your repository username and password. For GitHub and similar platforms, using a Personal Access Token is recommended to avoid credential retrieval errors in ArgoCD. Check your credentials in ArgoCD Settings post-deployment. Further information on handling private repositories in ArgoCD can be found here.
Execute cinchy.devops.automations
This utility updates the configurations in the cinchy.terraform
,
cinchy.argocd
, and cinchy.kubernetes
repositories.
- From a shell/terminal, navigate to the
cinchy.devops.automations
directory location and execute the following command:
dotnet Cinchy.DevOps.Automations.dll "deployment.json"
-
If the file created in "Configuring the Deployment.json" step 2 has a name other than
deployment.json
, the reference in the command will will need to be replaced with the correct name of the file. -
The console output should have the following message:
Completed successfully
Terraform deployment
The following steps detail how to deploy Terraform on AWS and Azure
- AWS
- Azure
The following section provides details for AWS deployment:
Cloud provider authentication
-
Launch a shell/terminal with the working directory set to the cluster directory within the cinchy.terraform repository.
-
Run the following commands to authenticate the session:
export AWS_DEFAULT_REGION=REGION
export AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY_ID
export AWS_SECRET_ACCESS_KEY=YOUR_ACCESS_KEY