Integration with Argo CD
Argo CD
This tutorial describes how to integrate a Yandex Managed Service for GitLab instance, a Managed Service for Kubernetes cluster, and Argo CD, as well as GitLab Runner installed in the cluster and building Docker containers using Kaniko
To integrate Argo CD with Managed Service for Kubernetes and Managed Service for GitLab:
- Create a GitLab instance
- Configure GitLab
- Create a GitLab Runner
- Prepare the application's repository to deploy
- Deploy your application using Argo CD
If you no longer need the resources you created, delete them.
Getting started
Prepare the infrastructure
-
If you do not have a network yet, create one.
-
If you do not have any subnets yet, create them in the availability zones where your Managed Service for Kubernetes cluster and node group will be created.
-
- Service account for Kubernetes resources with the
k8s.clusters.agent
andvpc.publicAdmin
roles for the folder where the Managed Service for Kubernetes cluster is created. - Service account for Managed Service for Kubernetes nodes with the container-registry.images.puller and container-registry.images.pusher roles. This service account will be used by the Managed Service for Kubernetes nodes to push the Docker images built in GitLab to the registry and pull them to run pods.
Tip
You can use the same service account to manage your Managed Service for Kubernetes cluster and its node groups.
- Service account for Kubernetes resources with the
-
Create security groups for the Managed Service for Kubernetes cluster and its node groups.
Warning
The configuration of security groups determines the performance and availability of the cluster and the services and applications running in it.
-
Create a security group for the Managed Service for GitLab instance.
-
Create a Managed Service for Kubernetes cluster and a node group. When creating a Managed Service for Kubernetes cluster, specify the previously created service accounts for resources and nodes as well as the security groups for the cluster.
-
Save the ID of the registry created, as you will need it at the next steps.
-
If you do not have Terraform yet, install it.
-
Get the authentication credentials. You can add them to environment variables or specify them later in the provider configuration file.
-
Configure and initialize a provider. There is no need to create a provider configuration file manually, you can download it
. -
Place the configuration file in a separate working directory and specify the parameter values. If you did not add the authentication credentials to environment variables, specify them in the configuration file.
-
Download the k8s-argocd.tf
Managed Service for Kubernetes cluster configuration file to the same working directory. The file describes:-
Managed Service for Kubernetes cluster.
-
Service account for Managed Service for Kubernetes resources and nodes.
-
Container Registry registry.
-
Security groups which contain rules required for the Managed Service for Kubernetes cluster and its node groups.
These security groups also contain the rules required for Managed Service for GitLab instance and Container Registry registry.
Warning
The configuration of security groups determines the performance and availability of the cluster and the services and applications running in it.
-
Specify the following in the configuration file:
- Folder ID.
- Kubernetes version for a Managed Service for Kubernetes cluster and node groups.
- Managed Service for Kubernetes cluster CIDR.
- Name of the service account for Managed Service for Kubernetes resources and nodes.
- Name of the Container Registry registry.
-
Make sure the Terraform configuration files are correct using this command:
terraform validate
If there are any errors in the configuration files, Terraform will point them out.
-
Create the required infrastructure:
-
Run the command to view planned changes:
terraform plan
If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.
-
If you are happy with the planned changes, apply them:
-
Run the command:
terraform apply
-
Confirm the update of resources.
-
Wait for the operation to complete.
-
All the required resources will be created in the specified folder. You can check resource availability and their settings in the management console
. -
Install additional dependencies
Install the following items in the local environment:
- Yandex Cloud command line interface (YC CLI)
jq
JSON stream processor- Helm package manager
-
Install kubectl
and configure it to work with the created cluster.
Create a GitLab instance
Create a Managed Service for GitLab instance or a VM with a GitLab image on the same cloud network as the Managed Service for Kubernetes cluster.
Create a Managed Service for GitLab instance by following this guide.
Launch GitLab on a VM with a public IP.
- On the folder page in the management console
, click Create resource and select Virtual machine instance. - In the Name field, enter the VM name as follows:
ci-tutorial-gitlab
. - Select an availability zone to place your VM in.
- Under Boot disk image, go to the Marketplace tab and click Show all Marketplace products. In the window that opens, select GitLab as your image and click Use.
- Under Computing resources, specify the following configuration:
- vCPU:
4
- Guaranteed vCPU performance:
100%
- RAM:
8 GB
- vCPU:
- Under Network settings:
-
Select a subnet to connect your VM to. If the required network or subnet is not listed, create it using the Create network and Create subnet buttons.
Warning
For the time being, Yandex Cloud technical restrictions do not allow selecting a subnet with an address range of
192.168.0.0/24
. -
In the Public IP field, select
Auto
.
-
- Under Access, specify the information required to access the instance:
-
Enter the username in the Login field.
Alert
Do not use the
root
username or other names reserved by the operating system. To perform operations that require superuser permissions, use thesudo
command. -
In the SSH key field, paste the contents of the public key file. You need to create a key pair for the SSH connection yourself. To learn how, see Connecting to a VM via SSH.
-
- Click Create VM.
It may take a few minutes to create the VM. When the VM changes its status to RUNNING
and GitLab starts, you can proceed to setup.
Configure GitLab
To configure GitLab and enable Continuous Integration (CI), create a new project and enter the CI authorization parameters:
-
Log in to the Managed Service for GitLab instance web interface.
-
Click Create a project.
-
Click Create blank project.
-
Fill out the fields below:
- Project name:
gitlab-test
. - Project URL: Select the administrator user in the field next to the Managed Service for GitLab instance FQDN.
Leave the other fields unchanged.
- Project name:
-
Click Create project.
-
On the Yandex Compute Cloud page, select the created VM and copy its public IP.
-
Connect to the VM via SSH.
-
Get the GitLab administrator password using the following VM command:
sudo cat /etc/gitlab/initial_root_password
-
Copy the password (without spaces) from the
Password
row to the clipboard or a separate file. -
Open
http://<VM_public_IP_address>
in your browser. This will take you to the GitLab web interface. -
Log in using the administrator account:
- Username or email:
root
- Password: Password you copied earlier
If you are unable to log in, reset the administrator account password
. - Username or email:
-
Log in to the system again using the administrator account and the new password.
-
Select Create a project.
-
Set the project name:
gitlab-test
. -
Click Create project.
Create a GitLab Runner
To run build tasks in the Yandex Managed Service for Kubernetes cluster, create a GitLab Runner
Once it is installed, you can run automated builds inside your Managed Service for Kubernetes cluster.
For more information about installing and running GitLab Runner, see the GitLab documentation
Prepare the application's repository to deploy
-
Get an authorized key for the previously created service account with the
container-registry.images.puller
andcontainer-registry.images.pusher
roles:yc iam key create --service-account-name <name_of_service_account_for_nodes> -o key.json
-
Save the contents of the key for the next step:
cat key.json | base64
-
Create the GitLab environment variables
:-
Go to Settings in the left-hand GitLab panel and select CI/CD from the drop-down list.
-
Click Expand next to Variables.
-
Add environment variables:
CI_REGISTRY
: Address of the previously created registry incr.yandex/<registry_ID>
format.CI_REGISTRY_USER
:json_key
.CI_REGISTRY_PASSWORD
: Output of thecat key.json | base64
command.
To add a variable:
- Click Add variable.
- In the window that opens, enter the variable name in the Key field and the value in the Value field.
- Click Add variable.
-
-
Set up access to the repository:
- Generate a new pair of SSH keys or use an existing one.
- Add a public part of the SSH key to the GitLab account settings
.
-
Clone the repository:
git clone git@<instance_name>.gitlab.yandexcloud.net:<admin_username>/gitlab-test.git
-
Clone the yc-webinar-gitops-argo-crossplane
repository to your instance:git clone https://github.com/yandex-cloud-examples/yc-webinar-gitops-argo-crossplane.git
-
To the
gitlab-test
directory, copy all files from theyc-webinar-gitops-argo-crossplane/02-argocd/app
directory, including hidden files:cp -rT <path_to_app_directory> <path_to_gitlab-test_directory>
-
Commit the changes to
gitlab-test
and push them to the repository:git add . && \ git commit -m "Add app src and CI" && \ git push
-
This will run the build script. To track its progress, in the drop-down menu, select Build → Pipelines. Wait until both build steps are complete.
-
Open the completed build and copy the following line from the log (you will need it at the next step):
INFO[0025] Pushing image to cr.yandex/<registry_ID>/<admin_username>/gitlab-test:main.<commit_number>
Deploy your application using Argo CD
Install Argo CD to the Managed Service for Kubernetes cluster
-
Install Argo CD by following this guide.
Warning
Kubernetes node groups require internet access to download images and components.
Internet access can be provided through:
- By assigning a public IP address to each node in the group.
- Configuring a VM as a NAT instance.
- Setting up a NAT gateway.
-
Configure ArgoCD port forwarding onto the local computer:
kubectl port-forward service/<Argo_CD_application_name>-argocd-server \ --namespace <namespace> 8080:443
-
Get the administrator password from a Kubernetes secret:
kubectl --namespace <namespace> get secret argocd-initial-admin-secret \ --output jsonpath="{.data.password}" | base64 -d
-
Open the Argo CD console at
https://127.0.0.1:8080
in your browser. -
Log in to the console as
admin
using the password obtained in the previous step.
Add a GitLab repository to Argo CD
-
Go to Settings in the left GitLab panel and select Access Tokens from the drop-down list.
-
Set parameters for a new token:
- Token name:
argocd
. - Select a role:
Maintainer
. - Select scopes:
read_repository
.
- Token name:
-
Click Create project access token.
-
Copy the value of the token you created.
-
In the Argo CD console, go to Settings → Repositories.
-
Click Connect Repo Using HTTPS.
-
In the resulting form, enter the settings:
- Repository URL: Repository URL in the following format:
https://<GitLab_instance_name>.gitlab.yandexcloud.net/<admin_username>/gitlab-test.git
. - Username:
gitlab-ci-token
. - Password: Previously generated GitLab token.
- Repository URL: Repository URL in the following format:
-
Click Connect.
-
In the Argo CD console, go to Applications, then click Create Application.
-
In the resulting form, enter the settings:
- Application Name:
gitlab-test
. - Project:
default
. - Sync policy:
Automatic
, then select Prune resources and Self Heal. - Sync options: Select the
Auto-Create Namespace
option. - Repository URL: Specify the repository URL, such as
https://<GitLab_instance_name>.gitlab.yandexcloud.net/<admin_username>/gitlab-test.git
. - Path:
.helm
. - Cluster URL:
https://kubernetes.default.svc
. - Namespace:
gitlab-test
. - image.repository:
cr.yandex/<registry_ID>/<admin_username>/gitlab-test
. - image.tag:
main.<commit_number>
.
- Application Name:
-
Click Create and wait until the syncing completes.
-
To test how the application runs, execute the following command in the Managed Service for Kubernetes cluster:
kubectl get all -n gitlab-test
Result:
NAME READY STATUS RESTARTS AGE pod/gitlab-test-67c8d58bc4-6w4q7 1/1 Running 0 2m26s pod/gitlab-test-67c8d58bc4-sldpc 1/1 Running 0 2m26s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/gitlab-test ClusterIP 10.96.186.223 <none> 80/TCP 2m26s NAME READY UP-TO-DATE AVAILABLE AGE deployment.apps/gitlab-test 2/2 2 2 2m26s NAME DESIRED CURRENT READY AGE replicaset.apps/gitlab-test-67c8d58bc4 2 2 2 2m26s
Test auto-syncing from the repository
-
Go to the directory with the cloned project and open the
.helm/values.yaml
file. -
Change the
replicaCount
parameter to3
. -
Save the changes and push them to the repository:
git add . && \ git commit -m "Increase replica count" && \ git push
-
In the Argo CD console, wait until the application is synced.
-
Make sure the number of application pods in the Managed Service for Kubernetes cluster has increased:
kubectl get pod -n gitlab-test
Result:
NAME READY STATUS RESTARTS AGE pod/gitlab-test-67c8d58bc4-6w4q7 1/1 Running 0 15m pod/gitlab-test-67c8d58bc4-7hmcn 1/1 Running 0 10m pod/gitlab-test-67c8d58bc4-sldpc 1/1 Running 0 15m NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/gitlab-test ClusterIP 10.96.186.223 <none> 80/TCP 15m NAME READY UP-TO-DATE AVAILABLE AGE deployment.apps/gitlab-test 3/3 3 3 15m NAME DESIRED CURRENT READY AGE replicaset.apps/gitlab-test-67c8d58bc4 3 3 3 15m
Delete the resources you created
Some resources are not free of charge. To avoid paying for them, delete the resources you no longer need:
-
Delete the Managed Service for Kubernetes cluster and Container Registry registry:
ManuallyTerraform-
In the command line, go to the directory with the current Terraform configuration file with an infrastructure plan.
-
Delete the
k8s-argocd.tf
configuration file. -
Make sure the Terraform configuration files are correct using this command:
terraform validate
If there are any errors in the configuration files, Terraform will point them out.
-
Confirm updating the resources.
-
Run the command to view planned changes:
terraform plan
If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.
-
If you are happy with the planned changes, apply them:
-
Run the command:
terraform apply
-
Confirm the update of resources.
-
Wait for the operation to complete.
-
All the resources described in the
k8s-argocd.tf
configuration file will be deleted. -
-
-
Delete the GitLab VM or Managed Service for GitLab instance you created.