Sobre os pacotes de frota

A API declarativa FleetPackage no Config Sync permite implantar e gerenciar pacotes de frota em clusters registrados em uma frota. Um pacote é um conjunto de manifestos YAML do Kubernetes que definem as configurações do cluster. Ao usar pacotes de frota, é possível implantar atualizações de configuração na frota de uma só vez ou progressivamente para reduzir o risco de interrupções amplas.

Você define cada objeto FleetPackage uma vez e, em seguida, atualiza esse pacote com novas revisões à medida que as configurações mudam. Quando você aplica uma nova revisão, o serviço de pacote de frota detecta automaticamente essas alterações e as implanta nos clusters de destino.

Vantagens

Os pacotes de frota se baseiam nos recursos do Config Sync, como a correção automática de desvios, e oferecem as seguintes vantagens:

• Automatizar o lançamento de recursos: depois de configurar um pacote de frota, os recursos do Kubernetes para os quais ele aponta são implantados automaticamente pelo serviço de pacote de frota em todos os clusters.

• Configurar novos clusters automaticamente: se você configurar um pacote de frota e depois adicionar novos clusters a uma frota, todos os recursos definidos pelo pacote de frota serão implantados automaticamente no novo cluster.

• Gerenciar a configuração do Kubernetes em escala: em vez de gerenciar clusters um por um, use pacotes de frota para implantar recursos em uma frota inteira de clusters.

• Minimize o impacto de mudanças incorretas: escolha um número máximo de clusters para implantar recursos de uma só vez. É possível monitorar de perto as mudanças em cada cluster para garantir que as alterações incorretas não afetem toda a frota.

• Simplifique a configuração do Config Sync: os pacotes de frota usam o Cloud Build para autenticar no Git, o que significa que você autentica uma vez por projeto, em vez de uma vez por objeto RootSync ou RepoSync.

Talvez você prefira usar o Config Sync com objetos RootSync ou RepoSync em vez de pacotes de frota se um ou mais dos seguintes cenários se aplicarem a você:

• Você gerencia um pequeno número de clusters.

• Você precisa de mais controle sobre como os recursos são implantados nos clusters, além do que a API de pacote de frota oferece com rótulos e variantes.

Requisitos e limitações

• Somente repositórios Git são compatíveis como fonte de verdade ao configurar um pacote de frota.

• Os recursos do Kubernetes armazenados no Git precisam representar o estado final do recurso. Não há suporte para sobreposições adicionais para transformar o recurso armazenado no Git. Para mais informações sobre as diferenças entre esses recursos, consulte Prática recomendada: criar repositórios WET.

• A API FleetPackage está disponível apenas na região us-central1. Ainda é possível implantar em clusters em diferentes regiões, mas é preciso configurar o Cloud Build e a CLI gcloud em us-central1.

• O número máximo de pacotes de frota é 300 por projeto por região.

Arquitetura

Use a API FleetPackage para implantar manifestos do Kubernetes em uma frota de clusters. A API FleetPackage usa o Cloud Build para sincronizar e buscar recursos do Kubernetes no repositório do Git. Em seguida, o serviço de pacote de frota implanta esses recursos nos clusters.

Como as variantes são geradas

Os pacotes de frota usam um sistema de variantes para implantar diferentes configurações de recursos do Kubernetes em diferentes clusters ou grupos de clusters na sua frota, mas do mesmo repositório do Git.

Há dois campos na especificação FleetPackage que controlam o comportamento das variantes:

1. resourceBundleSelector.cloudBuildRepository.variantsPattern: um padrão glob usado para encontrar arquivos e diretórios no repositório Git (no path especificado ou na raiz do repositório, se path for omitido). Esse padrão determina quais arquivos ou diretórios se tornam variantes e qual conteúdo eles incluem.
2. variantSelector.variantNameTemplate: uma expressão que mapeia cada cluster na frota para um dos nomes de variante gerados por variantsPattern. Essa seleção é baseada nos metadados de associação à frota do cluster.

Correspondência com variantsPattern

O campo variantsPattern é obrigatório para especificar como gerar variantes com base nas configurações armazenadas no repositório. A correspondência usa a seguinte lógica:

• Correspondência de arquivo: se o padrão corresponder a um arquivo YAML, uma variante será criada.

  • Nome da variante: o nome de arquivo sem a extensão (por exemplo, prod-config.yaml se torna a variante prod-config).
  • Conteúdo da variante: o conteúdo desse arquivo único.

• Correspondência de diretório: se o padrão corresponder a um diretório, uma variante será criada.

  • Nome da variante: o nome do diretório (por exemplo, o diretório dev se torna a variante dev).
  • Conteúdo da variante: a combinação de todos os arquivos YAML encontrados nesse diretório e em todos os subdiretórios dele, de forma recursiva.

Os padrões de correspondência de arquivos têm as seguintes limitações:

• Não use caracteres curinga recursivos (duplos). O padrão ** não é compatível.
• Se um padrão incluir um caractere de ponto (.), ele precisará ser seguido por um caractere alfanumérico.
• Os padrões não podem incluir aspas simples (').
• Os nomes das variantes precisam ser exclusivos. Se o padrão corresponder a vários arquivos com o mesmo nome (por exemplo, app1/deploy.yaml e app2/deploy.yaml), ambos vão tentar criar uma variante chamada deploy, causando uma colisão de nomes.

Por exemplo, considere um repositório com a seguinte estrutura:

repo-root/
└── FleetPackages/
    └── clusters/
        ├── common-ingress.yaml
        ├── us-central1-a/
        │   ├── gke-1/
        │   │   ├── deployment.yaml
        │   │   └── service.yaml
        │   └── gke-2/
        │       ├── deployment.yaml
        │       └── service.yaml
        └── us-central1-b/
            ├── gke-1.yaml
            └── blue-green.yaml

É possível corresponder e, portanto, sincronizar com seus clusters, arquivos diferentes, dependendo do tipo de correspondência de arquivo ou diretório que você define na especificação do pacote de frota, por exemplo:

• variantsPattern: "*": corresponde a common-ingress.yaml, us-central1-a e us-central1-b. Gera variantes:

  • common-ingress (do arquivo)
  • us-central1-a (combina todos os arquivos YAML dentro dessa pasta)
  • us-central1-b (combina todos os YAMLs nessa pasta)

• variantsPattern: "*.yaml": corresponde a common-ingress.yaml. Gera a variante:

  • common-ingress

• variantsPattern: "us-*": corresponde a us-central1-a e us-central1-b. Gera variantes:

  • us-central1-a
  • us-central1-b

• variantsPattern: "us-central1-b/*.yaml": corresponde a us-central1-b/gke-1.yaml e us-central1-b/blue-green.yaml. Gera variantes:

  • gke-1
  • blue-green

Correspondência com variantNameTemplate

Depois que as variantes são definidas, o campo variantNameTemplate na seção variantSelector determina qual variante é aplicada a cada cluster. O modelo pode usar variáveis para acessar os seguintes metadados de assinatura de frota:

• ${membership.name}: o nome da assinatura da frota do cluster.
• ${membership.location}: o local da assinatura da frota.
• ${membership.project}: o projeto de assinatura da frota.
• ${membership.labels['KEY']}: o valor do rótulo KEY na assinatura da frota.

Por exemplo, considere os seguintes cenários que usam rótulos para corresponder variantes:

• variantNameTemplate: "${membership.labels['env']}": um cluster com o rótulo env: prod é sincronizado com uma variante chamada prod.
• variantNameTemplate: "${membership.location}": os clusters são sincronizados com as variantes que correspondem ao local deles (por exemplo, us-central1-a).
• variantNameTemplate: "default": os clusters são sincronizados com uma variante chamada default. Esse é o comportamento padrão se variantSelector for omitido. Se o repositório não tiver um arquivo chamado default.yaml ou um diretório chamado default, nada será sincronizado.

Como combinar variantsPattern e variantNameTemplate

Para uma implantação bem-sucedida, verifique se os nomes de variantes gerados pelo variantsPattern são nomes com que os clusters podem ser sincronizados, correspondendo ao variantNameTemplate.

Por exemplo, para implantar em clusters com base em um rótulo de ambiente, estruture o repositório Git com diretórios como dev, staging e prod. Em seguida, use a seguinte especificação de pacote de frota:

resourceBundleSelector:
  cloudBuildRepository:
    # ... other fields
    path: "manifests"
    variantsPattern: "*" # Matches dev, staging, prod directories
variantSelector:
  variantNameTemplate: "${membership.labels['env']}"

Com essa configuração, um cluster rotulado como env: staging recebe o conteúdo do diretório manifests/staging/.

Estratégias de implantação

É possível usar pacotes de frota para implantar recursos de um repositório do Git em toda a frota de clusters. Também é possível configurar o pacote de frota para controlar como, onde e que tipo de recursos são implantados.

A seção a seguir mostra exemplos de diferentes configurações de FleetPackage. Para mais informações sobre como aplicar pacotes de frota, consulte Implantar pacotes de frota.

Implantação em todos os clusters de uma frota

O FleetPackage a seguir usa uma estratégia contínua para implantar recursos do Kubernetes em três clusters por vez e segmenta todos os clusters em uma frota:

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    variantsPattern: "*.yaml"
    serviceAccount: projects/my-project/serviceAccounts/[e-mail]
target:
  fleet:
    project: projects/my-project
rolloutStrategy:
  rolling:
    maxConcurrent: 3
variantSelector:
  variantNameTemplate: deployment # matches a file named deployment.yaml

Implantação em um subconjunto de clusters

O FleetPackage a seguir usa um seletor de rótulos para implantar recursos do Kubernetes apenas em clusters com o rótulo de associação country que corresponde a "us" na frota:

resourceBundleSelector:
  cloudBuildRepository:
    name: projects/my-project/locations/us-central1/connections/my-connection/repositories/my-repo
    tag: v1.0.0
    variantsPattern: "*.yaml"
    serviceAccount: projects/my-project/serviceAccounts/[e-mail]
target:
  fleet:
    project: projects/my-project
    selector:
      matchLabels:
        country: "us"
rolloutStrategy:
  rolling:
    maxConcurrent: 3

A seguir

Implantar pacotes de frota