Kubernetes Agent Installation and Registration

This feature is only available in self-hosted versions. Kubernetes cluster integration is currently not available on gitflic.ru

Important!

• Kubernetes cluster integration is in beta testing!
• The integration may contain bugs or inaccuracies!
• Please report any bugs or suggestions to support@gitflic.ru

To connect a Kubernetes cluster to GitFlic, you need to install an agent in the cluster.

Prerequisites

Before installing the agent in your cluster, you must:

• The self-hosted installation administrator must configure the Kubernetes agent proxy.

Agent Registration

Agent registration occurs in a GitFlic project. After registration and installation, you can configure the agent to connect to other projects. For agent registration, it's recommended to create a configuration file config.yaml at the following path:

.gitflic/agents/<agent-name>/config.yaml

<agent-name> - agent name. May contain Latin letters, numbers, and hyphens.

Agent connection is managed in the GitFlic interface: Project Settings -> Cluster Agents

Configuration File:

In the configuration file, you can specify either specific projects or teams whose projects will have access to the agent.

• Specific projects are specified in the format {ownerAlias}/{projectAlias}
• Teams are specified with their full path relative to the configuration file location. For example, company-1/team-1/subteam-1.

Path Parameter	Description
{ownerAlias}	Project owner's alias
{projectAlias}	Project alias

Example scenario for granting agent access:

• Specific project project-1 owned by company example-company
• Specific project project-2 owned by user example-user
• All projects owned by team team-1
• All projects of team team-2 owned by company-1

The configuration file would then look like this:

user_access:
    projects:
        - id: example-company/project-1
        - id: example-user/project-2
    teams:
        - id: team-1
        - id: company-1/team-2

Note:

You can only specify projects and teams for child entities of the repository where the configuration file is declared. Others will be ignored.

Depending on the repository owner of the configuration file, you can specify:

• Repository owned by a company:

  • Projects within that company or teams where the company is the root parent
  • Teams where the company is the root parent

• Repository owned by a team:

  • Projects within that team or teams inherited from the current one
  • Teams where the current team is the parent

Installing the Kubernetes Agent in the Cluster

For agent installation in a Kubernetes cluster, Helm is recommended.

To install the agent in a cluster using Helm:

1. Install Helm CLI
2. Open a terminal and connect to your Kubernetes cluster
3. Run the command displayed during Kubernetes agent registration in GitFlic. The command has the following format:

helm install <agent-name> oci://registry.gitflic.ru/helm/company/gitflic/kuber-agent-helm --version <gitflic-version> \
--namespace gitflic-agent-<agent-name> \
--create-namespace \
--set image.repository="registry.gitflic.ru/company/gitflic/kuber-agent"\
--set env.kuber_proxy_host=<kuber-proxy-host> \
--set env.kuber_proxy_port=<kuber-proxy-port> \
--set env.kuber_registration_token=<access_token>

Additional Helm Installation Settings

For simplicity, the default Helm configuration installs a service account for the agent with cluster-admin rights. This should not be used in production systems.

• You can: Skip service account creation by adding --set serviceAccount.create=false to the helm install command. In this case, you must set serviceAccount.name to an existing service account.

• Configure the role assigned to the service account by adding --set rbac.useExistingRole <your role name> to the helm install command. In this case, you must have a pre-created role with limited permissions that the service account can use.

• Skip role assignment entirely by adding --set rbac.create=false to your helm install command. In this case, you'll need to create the ClusterRoleBinding manually.

Cluster Interaction

After successfully completing all previous steps, you can interact with your Kubernetes cluster in your CI/CD processes.

Example usage in a get_pods task in your gitflic-ci.yaml:

get_pods:
  stage: deploy
  image:
    name: bitnami/kubectl:latest
    entrypoint: [ '' ]
  scripts:
    # Check namespaces in the cluster
    - kubectl get namespaces
    # Check pods within the connected Kubernetes agent's namespaces
    - kubectl get pods

Automatic translation!

This page has been automatically translated. The text may contain inaccuracies.