Using GitHub as Your Source of Truth with Argo CD

Article Content

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.

Kostis Kapelonis headshot
Kostis Kapelonis
Senior Developer Evangelist, Octopus Deploy
Kostis is a software engineer/technical-writer dual-class character. He lives and breathes automation, good testing practices, and stress-free deployments with GitOps.

TIPS FROM THE EXPERT

In my experience, here are tips that can help you better integrate Kubernetes with GitHub and manage your deployments using Argo CD:

  1. Use Argo CD’s app-of-apps pattern: Consider adopting the app-of-apps pattern in Argo CD for managing complex Kubernetes environments. This approach allows you to manage multiple applications and clusters by creating a master Argo CD application that manages other Argo CD applications, simplifying multi-tenant setups.
  2. Leverage GitHub Actions for pre-deployment validations: Before triggering deployments via Argo CD, use GitHub Actions to run linting, security checks, and configuration validation. This ensures only well-validated changes reach your Kubernetes cluster, reducing the likelihood of misconfigurations.
  3. Integrate with OPA/Gatekeeper for policy enforcement: Combine Argo CD with Open Policy Agent (OPA) and Gatekeeper to enforce custom policies on your Kubernetes resources. This adds a layer of compliance and security by ensuring that only configurations meeting your organization’s policies are deployed.
  4. Enable and customize Argo CD health checks: Customize the health checks in Argo CD for your specific workloads. This ensures that Argo CD only considers applications “healthy” when all critical services are running as expected, avoiding premature green statuses in your CI/CD pipeline.
  5. Implement branch-based environments: Utilize GitHub branches to represent different environments (e.g., dev, staging, prod). Argo CD can be configured to sync specific branches to corresponding Kubernetes environments, streamlining environment-specific deployments.

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 ArgoCD

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

kubectl create namespace argocd

2. Install ArgoCD Components

Next, apply the ArgoCD 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 ArgoCD from the command line, download the ArgoCD 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 ArgoCD 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 ArgoCD is installed and configured, you can proceed to connect your Kubernetes cluster to GitHub and deploy applications using ArgoCD.

Managing Private Git Repositories Within ArgoCD

When using private Git repositories with Argo CD, you need to configure the necessary credentials to allow access. ArgoCD 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.

ArgoCD 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 ArgoCD 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 ArgoCD UI by selecting Connect Repo using GitHub App and entering the required details.

Managing TLS Certificates

For repositories that require TLS client certificates, ArgoCD 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, ArgoCD can securely manage and deploy applications from private GitHub repositories.

Combine GitHub Actions with Codefresh to Support GitOps and Kubernetes Deployments

GitHub actions is a very powerful platform but it is focused mostly on CI and does not support GitOps and native Kubernetes deployments. Codefresh is created specifically for GitOps and Cloud native applications and includes native support for using GitHub Actions for the CI part of the Software lifecycle.

This means that you can get the best of both worlds by keeping all your CI workflows in GitHub Actions, while using Codefresh for advanced features such as:

  • Application dashboards
  • Git source managements
  • Configuration drift management
  • Kubernetes environment dashboards
  • Topology views

In case you are new to Codefresh – we have made it our mission since 2014 to help teams accelerate their pace of innovation. Codefresh recently released a completely rebuilt GitOps CI/CD toolset. Powered by Argo, Codefresh now combines the best of open source with an enterprise-grade runtime allowing you to fully tap the power of Argo Workflows, Events, CD, and Rollouts. It provides teams with a unified GitOps experience to build, test, deploy, and scale their applications.

Ready to Get Started?

Deploy more and fail less with Codefresh and Argo

Sign Up
Related Kubernetes Management articles