Amazon Elastic Kubernetes Service (EKS)
This page explains how to create a Kubernetes cluster using AWS Elastic Kubernetes Service and install Semaphore Community Edition.
Overview
If this is your first time using Semaphore we suggest trying out Semaphore Cloud to see if the platform fits your needs. You can create a free trial account without a credit card and use every feature.
The self-hosted installation is recommended for users and teams familiar with Semaphore.
There is a known issue that blocks Docker on macOS. If you have trouble running Helm and you're using macOS, check the following outstanding issue for a workaround.
Step 1 - Install dependencies
Install the following tools before starting the installation:
- AWS CLI: to manage your AWS resources
- Terraform: to create the Kubernetes cluster
- kubectl: to manage your Kubernetes installation
- Helm: to install Semaphore
In addition, you need to the domain where Semaphore will be installed to Route53 DNS. Take note of the hosted Zone ID for your domain within Route 53, for example, Z05666441V6R4KFL4MJAA, since it is used to create Semaphore infrastructure.
We highly recommend installing Semaphore on a subdomain, e.g. semaphore.example.com. Installing Semaphore on your main domain is discouraged as its operation might interfere with other services running on the same domain.
For example, if your domain is example.com, consider using the domain semaphore.example.com.
Step 2 - Clone the Semaphore repository
Clone the Semaphore repository to your machine with:
git clone https://github.com/semaphoreio/semaphore.git
Next, navigate to the EKS Terraform folder:
cd semaphore/ephemeral_environment/terraform/eks
Step 3 - Initialize your configuration
Initialize your AWS CLI configuration with:
aws configure
Create a configuration file called aws-config with the following values:
export DOMAIN="<domain-to-install-semaphore>"
export AWS_REGION="<your-aws-region>"
export ZONE_ID="<your-route53-zone-id>"
Once you are done with the configuration, it should look like this:
export DOMAIN="semaphore.example.com"
export AWS_REGION="eu-north-1"
export ZONE_ID="Z05198331K5V9MQ90PSP4"
Step 4 - Create the Kubernetes cluster
Load your configuration file with:
source aws-config
Create the EKS cluster using Terraform:
TF_VAR_aws_region=$AWS_REGION TF_VAR_route53_zone_id=$ZONE_ID TF_VAR_domain=$DOMAIN terraform apply
Once Terraform is done, retrieve the TLS certificate ARN with:
export CERT_NAME=$(terraform output ssl_cert_name)
Check the Terraform output for the name of the cluster and save the value in an environment variable:
export EKS_CLUSTER_NAME="<the-name-of-your-cluster>"
Save both new values to the aws-config file:
echo export CERT_NAME=${CERT_NAME} >> aws-config
echo export EKS_CLUSTER_NAME=${EKS_CLUSTER_NAME} >> aws-config
Step 5 - Install CRDs
Connect to the newly created cluster with:
aws eks update-kubeconfig --name "${EKS_CLUSTER_NAME}" --region "${AWS_REGION}"
Semaphore requires the [Emissary CRDs] to be installed on the cluster. Install the Custom Resource Definitions (CRDs) with the following commands:
kubectl apply -f https://app.getambassador.io/yaml/emissary/3.9.1/emissary-crds.yaml
kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system
Step 6 - Install Semaphore
Sanity check that the environment is ready for the installation. The commands should not fail and return valid values:
source aws-config
echo "DOMAIN=${DOMAIN}"
echo "CERT_NAME=${CERT_NAME}"
Install Semaphore with Helm:
helm upgrade --install --debug semaphore oci://ghcr.io/semaphoreio/semaphore \
--version v1.0.1 \
--timeout 20m \
--set global.domain.name="${DOMAIN}" \
--set ingress.ssl.certName="${CERT_NAME}" \
--set ingress.className=alb \
--set ssl.type=alb
Once the installation is done, you the following command should appear in the terminal:
=============================================================================================
Congratulations, Semaphore has been installed successfully!
To start using the app, go to https://id.semaphore.example.com/login
You can fetch credentials for the login by running this command:
echo "Email: $(kubectl get secret root-user -n default -o jsonpath='{.data.email}' | base64 -d)"; echo "Password: $(kubectl get secret root-user -n default -o jsonpath='{.data.password}' | base64 -d)"; echo "API Token: $(kubectl get secret root-user -n default -o jsonpath='{.data.token}' | base64 -d)"
=============================================================================================
Execute the shown command to retrieve the login credentials.
$ echo "Email: $(kubectl get secret root-user -n default -o jsonpath='{.data.email}' | base64 -d)"; echo "Password: $(kubectl get secret root-user -n default -o jsonpath='{.data.password}' | base64 -d)"; echo "API Token: $(kubectl get secret root-user -n default -o jsonpath='{.data.token}' | base64 -d)"
Email: root@example.com
Password: AhGg_2v6uHuy7hqvNmeLw0O4RqI=
API Token: nQjnaPKQvW6TqXtpTNSx
Step 7 - First login
On new installations, the system may take up to 30 minutes to finish all setup tasks. If you cannot login right away, wait a few minutes and try again.
Open a browser and navigate to the domain to id.<your-domain>/login. For example: id.semaphore.example.com/login
Fill in the username and password obtained at the end of step 6.
Once logged in, select the Semaphore organization to continue.
You should be greeted with the onboarding guide.
Post-installation tasks
Once your have Semaphore up and running, check out the following pages to finish setting up:
- Connect with GitHub: connect your instance with GitHub to access your repositories
- Invite users: invite users to your instance so they can start working on projects
- Guided tour: complete the guided tour to get familiarized with Semaphore Community Edition
- Add self-hosted agents: add more machines to scale up the capacity of your CI/CD platform
How to Uninstall Semaphore from EKS
If you want to completely uninstall Semaphore, follow these steps.
If you uninstall Semaphore you will lose access to all your projects, workflows and logs. You cannot undo this action.
First, uninstall Semaphore with the following command:
source aws-config
helm uninstall semaphore
Delete the persistent volume claims:
kubectl delete pvc \
minio-artifacts-storage-minio-artifacts-0 \
minio-cache-storage-minio-cache-0 \
minio-logs-storage-minio-logs-0 \
postgres-storage-postgres-0 \
rabbitmq-storage-rabbitmq-0 \
redis-data-redis-0
Finally, if you are no longer using the Kubernetes cluster, you may delete it with the following command. This completely destroys the Kubernetes cluster with any other things you might be running there.
cd semaphore/ephemeral_environment/terraform/eks
terraform destroy
You will be prompted to confirm the deletion of the AWS resources.