튜토리얼: GitOps를 위한 Flux 설정

Tier: Free, Premium, Ultimate

Offering: GitLab.com, Self-managed, GitLab Dedicated

이 튜토리얼은 GitOps를 위해 Flux를 설정하는 방법을 가르쳐 줍니다. 부트스트랩 설치를 완료하고, 클러스터에 agentk를 설치하며, 간단한 nginx 애플리케이션을 배포합니다.

Flux 구성 예제 개요는 Flux bootstrap 및 GitLab과의 매니페스트 동기화를 참조하세요.

GitOps를 위해 Flux를 설정하려면:

  1. 개인 액세스 토큰 생성하기
  2. 부트스트랩 설치 완료하기
  3. agentk 등록하기
  4. agentk 설치하기
  5. 예제 프로젝트 배포하기

사전 요구 사항:

  • kubectl로 접근할 수 있는 Kubernetes 클러스터가 있어야 합니다.

  • Flux CLI를 설치해야 합니다. Flux v2 이상을 설치했는지 확인하세요.

개인 액세스 토큰 생성하기

Flux CLI에 인증하기 위해 api 범위를 가진 개인 액세스 토큰을 생성합니다:

  1. 왼쪽 사이드바에서 아바타를 선택합니다.
  2. 프로필 수정을 선택합니다.
  3. 왼쪽 사이드바에서 액세스 토큰을 선택합니다.
  4. 토큰의 이름과 선택적 만료 날짜를 입력합니다.
  5. api 범위를 선택합니다.
  6. 개인 액세스 토큰 만들기를 선택합니다.

api 범위와 developer 역할이 있는 프로젝트 또는 그룹 액세스 토큰도 사용할 수 있습니다.

부트스트랩 설치 완료하기

이 섹션에서는 빈 GitLab 리포지토리에 Flux를 부트스트랩합니다. flux bootstrap 명령을 사용합니다.

Flux 설치를 부트스트랩하려면:

  • flux bootstrap gitlab 명령을 실행합니다. 예를 들어:

    flux bootstrap gitlab \
--hostname=gitlab.example.org \
--owner=example-org \
--repository=my-repository \
--branch=master \
--path=clusters/testing \
--deploy-token-auth

bootstrap의 매개변수는 다음과 같습니다:

Argument Description
hostname 당신의 GitLab 인스턴스의 호스트 이름입니다.
owner Flux 리포지토리를 포함하는 GitLab 그룹입니다.
repository Flux 리포지토리를 포함하는 GitLab 프로젝트입니다.
branch 변경 사항이 커밋되는 Git 브랜치입니다.
path Flux 구성 파일이 저장될 폴더의 파일 경로입니다.

부트스트랩 스크립트는 다음을 수행합니다:

  1. 배포 토큰을 생성하고 이를 Kubernetes secret로 저장합니다.

  2. --repository 인수로 지정된 프로젝트가 존재하지 않는 경우 빈 GitLab 프로젝트를 생성합니다.

  3. --path 인수로 지정된 폴더에 대한 프로젝트의 Flux 정의 파일을 생성합니다.

  4. 정의 파일을 --branch 인수로 지정된 브랜치에 커밋합니다.

  5. 정의 파일을 클러스터에 적용합니다.

스크립트를 실행한 후 Flux는 자신과 GitLab 프로젝트 및 경로에 추가된 다른 리소스를 관리할 준비가 됩니다.

이 튜토리얼의 나머지 부분은 경로가 clusters/testing이라고 가정합니다.

Flux 업그레이드

설치한 후에 Flux를 업그레이드할 필요가 있을 수 있습니다. 그렇게 하려면:

  • flux bootstrap gitlab 명령어를 다시 실행합니다.

agentk 등록

클러스터에 설치하기 전에 agentk를 등록해야 합니다.

agentk를 등록하려면:

  1. 왼쪽 사이드바에서 검색하거나 이동을 선택하고 프로젝트를 찾습니다.
    에이전트 구성 파일이 있으면
    이 프로젝트에 있어야 합니다. 클러스터 매니페스트 파일도 이 프로젝트에 있어야 합니다.

  2. 작업 > Kubernetes 클러스터를 선택합니다.

  3. 클러스터 연결 (에이전트)를 선택합니다.
    • CI/CD 기본값으로 구성을 생성하려면 이름을 입력합니다.
    • 이미 에이전트 구성 파일이 있는 경우 목록에서 선택합니다.

  4. 에이전트 등록을 선택합니다.

  5. 에이전트 액세스 토큰과 kasAddress를 안전하게 저장합니다.

에이전트가 귀하의 프로젝트에 등록되었습니다. 아직 명령을 실행할 필요는 없습니다.

다음 단계에서는 Flux를 사용하여 클러스터에 agentk를 설치합니다.

agentk 설치

다음으로, Flux를 사용하여 agentk를 위한 네임스페이스를 생성하고 클러스터에 설치합니다.
Flux가 리포지토리에서 정의된 구성 변경 사항을 인식하고 적용하는 데 몇 분이 걸릴 수 있습니다.

이 튜토리얼에서는 agentk를 위해 네임스페이스 gitlab을 사용합니다.

agentk를 설치하려면:

  1. 다음 파일을 clusters/testing/namespace-gitlab.yaml에 커밋하고 푸시합니다:

    apiVersion: v1
kind: Namespace
metadata:
  name: gitlab

  2. 에이전트 액세스 토큰을 비밀로 포함하는 secret.yaml라는 파일을 생성합니다:

    apiVersion: v1
kind: Secret
metadata:
  name: gitlab-agent-token
  namespace: gitlab
type: Opaque
stringData:
   token: "<your-token-here>"

  3. secret.yaml을 클러스터에 적용합니다:

    kubectl apply -f secret.yaml -n gitlab

    이 단계는 GitOps 원칙을 따르지 않지만, 새로운 Flux 사용자에게 구성을 단순화합니다.
    적절한 GitOps 설정을 위해서는 비밀 관리 솔루션을 사용해야 합니다. Flux 문서를 참조하세요.

  4. 다음 파일을 clusters/testing/agentk.yaml에 커밋하고 푸시하며,
    .spec.values.config.kasAddress와 .spec.values.config.secretName의 값을 저장한 kas 주소와 비밀 이름으로 변경합니다:

    ---
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: HelmRepository
metadata:
  labels:
    app.kubernetes.io/component: agentk
    app.kubernetes.io/created-by: gitlab
    app.kubernetes.io/name: agentk
    app.kubernetes.io/part-of: gitlab
  name: gitlab-agent
  namespace: gitlab
spec:
  interval: 1h0m0s
  url: https://charts.gitlab.io
---
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
  name: gitlab-agent
  namespace: gitlab
spec:
  chart:
    spec:
      chart: gitlab-agent
      sourceRef:
        kind: HelmRepository
        name: gitlab-agent
        namespace: gitlab
  interval: 1h0m0s
  values:
    config:
      kasAddress: "wss://kas.gitlab.com"
      secretName: gitlab-agent-token

    Helm 릴리스는 이전 단계에서 가져온 비밀을 사용합니다.

  5. 클러스터에 agentk가 설치되고 실행 중인지 확인하려면 다음 명령어를 실행합니다:

    kubectl -n gitlab get pods

잘 하셨습니다! agentk와 함께 Flux를 성공적으로 설정했습니다.
이 섹션의 단계를 반복하여 이 프로젝트에서 더 많은 애플리케이션을 배포할 수 있습니다.
다음 섹션에서는 Flux를 여러 프로젝트에 걸쳐 확장하는 방법에 대해 논의하겠습니다.

예제 프로젝트 배포

여러 GitLab 프로젝트에서 Flux 배포를 확장할 수 있습니다. 다른 프로젝트를 가리키는 Flux GitRepository 및 Kustomization을 추가하여 가능합니다.

이 기능을 사용하여 특정 GitLab 그룹과 관련된 매니페스트를 해당 그룹에 저장할 수 있습니다.

예를 들어, nginx 애플리케이션을 배포하고 Flux를 그에 맞추어 설정해 보겠습니다:

  1. 다음 파일을 clusters/testing/example-nginx-app.yaml에 커밋하고 푸시하십시오:

    ---
apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: example-nginx-app
  namespace: flux-system
spec:
  interval: 1m0s
  ref:
    branch: main
  url: https://gitlab.com/gitlab-examples/ops/gitops-demo/example-mini-flux-deployment.git
---
apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: example-nginx-app
  namespace: flux-system
spec:
  interval: 10m0s
  path: ./manifests
  prune: true
  sourceRef:
    kind: GitRepository
    name: example-nginx-app

  2. 애플리케이션이 올바르게 배포되었는지와 agentk가 실행 중인지 확인하려면 다음 명령을 실행하십시오:

    kubectl -n example-nginx get pods

이 튜토리얼은 공개 프로젝트에서 애플리케이션을 배포합니다. 비공식 프로젝트를 추가하려면 프로젝트 배포 토큰을 생성하고 Flux 비밀로 저장해야 합니다. 네임스페이스와 비밀 이름을 반드시 저장하십시오.

축하합니다! 여러 그룹 및 프로젝트에 걸쳐 Flux를 성공적으로 확장했습니다.