Configurar o Kubernetes com Kustomize

O objetivo deste documento é ajudar você a começar a usar o Kustomize, a entender os casos de uso pretendidos e a encontrar recursos para usá-lo com outras ferramentas do Google Cloud.

O Kustomize é uma ferramenta de transformação de configuração do Kubernetes que permite personalizar arquivos YAML sem modelos, deixando os arquivos originais intactos. O Kustomize também gera recursos como ConfigMaps e Secrets de outras representações. O Kustomize foi criado para a API Kubernetes, por isso consegue entender e modificar objetos no estilo Kubernetes.

Sobre o Kustomize

Criado pelo Google e pela comunidade do Kubernetes, o Kustomize se alinha aos princípios do Kubernetes ao usar objetos do Kubernetes para definir arquivos de configuração e gerenciar as configurações de maneira declarativa. O objeto de configuração do Kustomize é chamado de Kustomization, que descreve como gerar ou transformar outros objetos do Kubernetes. Uma Kustomization é definida de modo declarativo em um arquivo chamado kustomization.yaml, que pode ser gerado e editado pelo próprio Kustomize.

No Kustomize, é possível definir uma kustomization comum e reutilizável (chamada base) e corrigi-la com várias outras (conhecidas como sobreposições), que podem substituir seletivamente as configurações definidas na base para produzir variantes. Em seguida, o Kustomize transforma e gera recursos, um processo chamado de hidratação ou renderização, de acordo com a configuração definida nas bases e sobreposições de kustomization. Esses recursos renderizados são gravados na saída padrão ou em arquivos, deixando os arquivos YAML originais intactos para que uma base possa ser reutilizada por muitas sobreposições diferentes.

imagem

Essa abordagem sem modelos é eficiente quando se trata da facilidade de uso e da reutilização de bases de kustomization. Com ela, é possível personalizar a configuração do Kubernetes de praticamente qualquer maneira que você quiser, sem precisar fornecer um grande conjunto de valores para cada caso de uso individual.

Benefícios do Kustomize

Os benefícios de gerenciar configurações do Kubernetes com o Kustomize incluem:

O Kustomize não usa modelos. Ao usar modelos e arquivos de valor, quase todas as especificações de um arquivo YAML podem se tornar parâmetros que precisam de valores, e os arquivos de valor podem ficar muito grandes. Em vez de modelar a configuração como texto ou expressá-la como código, o Kustomize manipula dados de configuração. O YAML bruto pode ser lido e reutilizado, seja ele renderizado pelo Kustomize ou não. O modelo do Kustomize é diferente. Não é necessário parametrizar tudo, o que facilita a reutilização de configurações comuns.
O Kustomize pode ser executado de forma nativa na interface de linha de comando do Kubernetes. O Kustomize está integrado ao kubectl, a partir da versão 1.14. Portanto, contanto que você use kubectl, não será necessário instalar nem gerenciar o Kustomize como uma dependência separada.
O Kustomize é puramente declarativo. Por ser uma ferramenta nativa do Kubernetes, o Kustomize está alinhado com a abordagem do Kubernetes para configuração declarativa. Em vez de descrever passo a passo como a ferramenta precisa personalizar os recursos, você declara o que quer e o Kustomize fornece.
O Kustomize permite que você reutilize a mesma configuração de base para gerenciar várias configurações diferentes. É possível usar um arquivo de base em vários ambientes diferentes (por exemplo, desenvolvimento, preparação e produção) e ter sobreposições mínimas e exclusivas para personalizar a base para cada ambiente.
O Kustomize é fácil de usar. A curva de aprendizagem é tranquila. Comece com uma configuração muito simples e crie recursos mais complexos gradualmente, uma camada por vez.
O Kustomize é extensível e personalizável. O Kustomize é compatível com um framework de plug-in para você criar seus próprios geradores e transformadores no estilo de funções de Modelo de Recurso do Kubernetes (KRM, na sigla em inglês) executáveis e conteinerizadas. Para saber mais sobre como criar seus próprios plug-ins, leia o Guia de plug-ins do Kustomize oficial.

Instalação local

Para instalar o Kustomize no ambiente local, execute o seguinte comando:

gcloud components install kustomize

Suporte do Kustomize no Google Cloud

O Kustomize está pré-instalado no Cloud Shell e é compatível com o Skaffold. Ele também pode ser usado como criador do Cloud Build.

O Config Sync usa automaticamente o Kustomize para renderizar os recursos em um repositório se houver um arquivo de kustomização. Saiba mais sobre esse recurso em Usar um repo com configurações do Kustomize e gráficos Helm.

Como funciona o Kustomize

Bases e sobreposições

A abordagem de transformação de configuração do Kustomize aproveita o uso de camadas de kustomization para que os mesmos arquivos de configuração de base possam ser reutilizados em várias configurações. Isso funciona com os conceitos de bases e sobreposições.

Uma base é um diretório que contém um arquivo chamado kustomization.yaml, que pode enumerar algum conjunto de recursos com personalizações que serão aplicadas a eles. A base precisa ser declarada no campo resources de um arquivo de kustomization.
Uma sobreposição é um diretório que se refere a outro diretório de kustomization como a base dele ou uma das bases dele.

Uma base pode ser considerada como uma etapa preliminar em um pipeline, sem conhecimento das sobreposições referenciadas. Depois que o processamento de uma base é concluído, ele envia os recursos como entrada para a sobreposição transformar de acordo com as respectivas especificações.

Veja a seguir um exemplo de uma base de kustomization:

# base/kustomization.yaml
resources:
- deployment.yaml
namePrefix: bar-

#base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  template:
    metadata:
    spec:
      containers:
      - image: nginx
        name: nginx

Essa base pode ser reutilizada por várias sobreposições. Veja a seguir um exemplo de sobreposição que pode se referir a essa base:

# overlay/kustomization.yaml
resources:
- ../base
- configmap.yaml
namePrefix: foo-

#overlay/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: cm
data:
  red: blue

A execução do comando kustomize build overlay produz a seguinte saída:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: foo-bar-nginx
spec:
  template:
    metadata:
    spec:
      containers:
      - image: nginx
        name: nginx
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: foo-cm
data:
  red: blue

A implantação recebeu o prefixo de nome bar- da kustomization de base e, em seguida, outro prefixo de nome foo- da kustomization de sobreposição. O ConfigMap recebeu apenas o prefixo de nome foo- porque foi declarado na sobreposição e, portanto, foi processado somente pela sobreposição.

Gerar secrets e ConfigMaps

É possível gerar secrets e ConfigMaps a partir de um arquivo usando os campos secretGenerator ou configMapGenerator no arquivo de kustomization. Exemplo:

# kustomization.yaml
configMapGenerator:
- name: my-app
  files:
  -.properties

gera a seguinte saída YAML:

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-app-g82klmn92h
data:
  .properties: |-
      red=blue

Editar o arquivo de kustomization

O Kustomize fornece vários comandos imperativos que ajudam a gerenciar o arquivo de kustomization.

Para adicionar todos os arquivos YAML do diretório atual ao campo resources de kustomization, execute o seguinte comando:
```
kustomize edit add resource *.yaml
```
Para visualizar a página de ajuda de edição do Kustomize e ver todos os subcomandos que ela oferece, execute o seguinte comando:
```
kustomize edit -h
```
Para receber ajuda específica sobre os subcomandos, adicione-o como argumento. Exemplo:
```
kustomize edit add -h
```

A seguir

Documentação oficial

Para mais informações sobre os campos compatíveis com o arquivo kustomization.yaml, acesse os documentos oficiais do Kustomize, que apresentam descrições e exemplos dos vários campos possíveis de usar.

Recursos não suportados

Para uma lista de recursos que não são compatíveis com o Kustomize intencionalmente, leia sobre os recursos rejeitados do Kustomize.