Using GitHub as your source of truth with Argo CD

What is Kubernetes?

Kubernetes is an open-source container orchestration platform. It automates the deployment, scaling, and management of containerized applications. It was originally developed by Google, and is now the most popular tool for orchestrating applications across various environments, ensuring scalability, and maintaining high availability.

Kubernetes orchestrates containerized applications to ensure they run optimally. It achieves this by managing resources, scheduling workloads, and providing tools for application upgrades and rollbacks. Kubernetes is integral to modern cloud-native computing, playing a role in abstracting infrastructure complexity and delivering reliable services.

What is GitHub?

GitHub is a web-based platform for version control and collaboration, used by over 100 million developers. It uses Git, the popular version control system, to enable multiple developers to work on projects simultaneously. GitHub hosts code repositories, provides tools for code review, and integrates with numerous third-party services to enhance the development workflow.

Beyond version control, GitHub is a social platform where developers share their projects, contribute to open-source software, and engage in collaborative development. Its ecosystem includes features like pull requests, issues, and GitHub Actions, which facilitate continuous integration and deployment pipelines.

This is part of a series of articles about Kubernetes management

Benefits of integrating Kubernetes with GitHub

GitOps workflow

A GitOps workflow uses Git repositories as the single source of truth for infrastructure and application code. By integrating Kubernetes with GitHub, operations teams can manage Kubernetes clusters declaratively using Git pull requests. This simplifies the change management process and enhances traceability.

With GitOps, any update to the infrastructure or application configuration is made in the Git repository. Kubernetes continuously synchronizes its state with the repository, ensuring consistent deployment. GitOps augments Kubernetes’ native capabilities, fostering a reliable, automated, and auditable deployment process.

Version control and history

Version control is a core aspect of integrating Kubernetes with GitHub. GitHub’s branch and merge makes it possible to maintain multiple versions of an application, enabling teams to experiment with new features without affecting the main codebase. Each change is tracked and can be reviewed before merging into the production branch.

The history provided by GitHub aids in auditing and troubleshooting. Teams can trace back through commits to understand changes, identify the introduction of bugs, and restore previous configurations if needed. This version control mechanism ensures that applications remain stable and that any issues can be swiftly addressed.

Collaboration and team efficiency

GitHub’s features, such as pull requests and code reviews, allow teams to collaborate effectively. Developers can propose changes, review code, and discuss improvements within the platform, fostering a collaborative development environment.

The integration streamlines DevOps practices. Automated CI/CD pipelines can be configured to trigger Kubernetes deployments from GitHub, reducing manual intervention and speeding up the release cycle. This continuous feedback loop enhances productivity and accelerates the delivery of high-quality software.

Improved security and compliance

When integrating Kubernetes with GitHub, version-controlled deployment manifests ensure that only audited and approved configurations are applied to the Kubernetes cluster. This minimizes the risks associated with ad-hoc changes and unauthorized modifications.

Security policies can be enforced through GitHub workflows to ensure compliance with organizational standards. Changes in the repository can trigger automated security checks and vulnerability scans. Thus, integrating these platforms provides a secure environment where compliance is maintained, and potential vulnerabilities are identified and mitigated promptly.

What is Argo CD?

Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes. It enables users to automate the deployment and management of Kubernetes applications by monitoring changes in a Git repository and applying these changes to the Kubernetes cluster. Argo CD ensures that the cluster’s state matches the repository, thus supporting GitOps practices.

Argo CD works with multiple Git providers, including GitHub, making it a versatile solution for various workflows. It provides features such as application rollback, real-time monitoring, and health checks. By using Argo CD, teams can enhance their deployment strategies, achieve higher reliability, and ensure that application states are consistent with their desired configurations.

Tutorial: connecting Kubernetes to GitHub with Argo CD

To connect Kubernetes to GitHub with Argo CD, follow these steps:

Install Argo CD

To install Argo CD on your Kubernetes cluster, follow these steps:

1. Create a namespace for Argo CD

   First, create a namespace called argocd where the Argo CD resources will be deployed. This can be done using the following command:

   kubectl create namespace argocd

2. Install Argo CD components

   Next, apply the Argo CD installation manifest to deploy the necessary components. Run the following command:

   kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

   This command deploys Argo CD with a self-signed certificate by default. If you plan to use a different namespace, update the namespace reference in the manifest accordingly.

3. Access the Argo CD API server

   The Argo CD API server is not exposed with an external IP by default. To access it, you can choose one of the following methods:

   Service type LoadBalancer: Modify the service type to LoadBalancer by running:

   kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "LoadBalancer"}}'

   Port forwarding: Alternatively, you can use kubectl port-forwarding, and then access the API server via https://localhost:8080.

   kubectl port-forward svc/argocd-server -n argocd 8080:443

4. Download Argo CD CLI

   To manage Argo CD from the command line, download the Argo CD CLI from the official GitHub releases page. You can also install it using Homebrew for macOS, Linux, or WSL:

   brew install argocd

5. Login to Argo CD

   Retrieve the initial password for the admin account stored in the argocd-initial-admin-secret Kubernetes secret. Use the following command:

   argocd admin initial-password -n argocd

   Then, log in to the Argo CD server:

   argocd login <ARGOCD_SERVER>

Replace <ARGOCD_SERVER> with the actual server IP or hostname. It’s recommended to delete the argocd-initial-admin-secret after changing the password for security reasons.

Now that Argo CD is installed and configured, you can proceed to connect your Kubernetes cluster to GitHub and deploy applications using Argo CD.

Managing private Git repositories within Argo CD

When using private Git repositories with Argo CD, you need to configure the necessary credentials to allow access. Argo CD supports multiple authentication methods, including HTTPS, SSH, and GitHub App credentials.

HTTPS authentication

For repositories requiring a username and password, Argo CD allows you to add these credentials either through the command line or the web UI. You can use the following CLI command:

argocd repo add <repository-url> --username <username> --password <password>

Alternatively, you can configure this via the Argo CD UI by navigating to Settings > Repositories, selecting Connect Repo using HTTPS, and entering your credentials.

If your repository uses an access token instead of a password, you can generate this token from your Git hosting service and use it in place of the password. Some services may require you to specify your account name as the username when using an access token.

SSH authentication

For repositories accessed via SSH, you will need to provide the SSH private key. This can be done through the CLI:

argocd repo add <repository-url> --ssh-private-key-path ~/.ssh/id_rsa

Or via the Argo CD UI by selecting Connect Repo using SSH and pasting your SSH private key into the provided field.

Argo CD also allows you to handle SSH known hosts securely by adding the server’s SSH public host key using the argocd cert add-ssh command.

GitHub App authentication

For private repositories hosted on GitHub, you can use a GitHub App for authentication. First, create a GitHub App with the necessary permissions, then connect the repository in Argo CD using the following CLI command:

argocd repo add <repository-url> --github-app-id <app-id> --github-app-installation-id <installation-id> --github-app-private-key-path <path-to-private-key>

Alternatively, this can be set up in the Argo CD UI by selecting Connect Repo using GitHub App and entering the required details.

Managing TLS certificates

For repositories that require TLS client certificates, Argo CD supports the addition of these certificates through the CLI:

argocd repo add <repository-url> --tls-client-cert-path ~/mycert.crt --tls-client-cert-key-path ~/mycert.key

This configuration ensures secure access to the repository, complying with your organization’s security policies.

By properly setting up these credentials and certificates, Argo CD can securely manage and deploy applications from private GitHub repositories.

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback