Sobre os pacotes de frota

Nesta página, explicamos os pacotes da frota, a API FleetPackage e como eles se relacionam com o Config Sync.

Um FleetPackage é uma API declarativa que permite gerenciar pacotes em uma frota. Um pacote de frota é um conjunto de manifestos YAML do Kubernetes que definem a configuração do cluster. Ao usar pacotes de frota, você pode implantar pacotes com um lançamento progressivo ou de uma só vez em clusters registrados na sua frota.

Você define cada objeto FleetPackage uma vez e depois pode atualizar esse pacote com uma nova revisão. Quando você aplica uma nova revisão, o serviço de pacote da frota coleta essas mudanças e as implanta nos clusters.

Vantagens

Use pacotes de frota para implantar recursos do Kubernetes em clusters registrados em uma frota. Depois de criar e aplicar um pacote de frota, ele implanta automaticamente os arquivos de configuração do Kubernetes no repositório Git para o novo cluster. Os pacotes da frota aproveitam os benefícios do Config Sync, como a correção automática de desvios, e oferecem as seguintes vantagens exclusivas:

• Automatizar o lançamento de recursos:depois de configurar um pacote da frota, os recursos do Kubernetes a que ele se refere são implantados automaticamente pelo serviço de pacote da 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 grande escala:em vez de gerenciar clusters um por um, use pacotes da frota para implantar recursos em toda a frota de clusters.

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

• Simplifique a configuração do Config Sync:os pacotes da frota usam o Cloud Build para autenticar no Git. Isso significa que você se 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 do pacote de frota oferece com rótulos e variantes.

Requisitos e limitações

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

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

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

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

Arquitetura

É possível usar 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 seu repositório Git. Em seguida, o serviço de pacote de frota implanta esses recursos nos seus 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 seu 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 sua frota para um dos nomes de variantes gerados por variantsPattern. Essa seleção é baseada nos metadados da assinatura da frota do cluster.

Correspondência com variantsPattern

O campo variantsPattern é obrigatório para especificar como gerar variantes das 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 do arquivo sem a extensão (por exemplo, prod-config.yaml se torna a variante prod-config).
  • Conteúdo da variante:o conteúdo deste único arquivo.

• 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 neste 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 há caracteres curinga recursivos (duplos). O padrão ** não é compatível.
• Se um padrão incluir um 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 tentarão 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 diferentes arquivos, dependendo do tipo de correspondência de arquivo ou diretório que você define na especificação do pacote da 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 (combinando todos os arquivos YAML nessa pasta)
  • us-central1-b (combinando todos os YAMLs na pasta)

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

  • 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 associação da frota:

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

Por exemplo, considere os seguintes cenários que usam rótulos para corresponder a 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 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 que seus clusters podem sincronizar correspondendo ao variantNameTemplate.

Por exemplo, para fazer a implantação em clusters com base em um rótulo de ambiente, você pode estruturar seu repositório Git com diretórios como dev, staging e prod. Em seguida, use a seguinte especificação de pacote da 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

Use pacotes de frota para implantar recursos de um repositório Git em toda a frota de clusters. Também é possível configurar o pacote da frota para controlar como, onde e qual 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 gradual para implantar recursos do Kubernetes em três clusters por vez e tem como destino 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