Ignorar campos não especificados

---

Este documento explica como alterar os campos de especificação padrão que preenchem o comportamento usando a anotação cnrm.cloud.google.com/state-into-spec e quando é necessário alterá-la.

Conforme explicado em Gerenciar campos externamente, quando o Config Connector cria um recurso no Google Cloud, os campos deixados não especificados na especificação assumem valores da API, a menos que não sejam legíveis (por exemplo, não estão disponíveis usando uma solicitação HTTP GET).

Isso significa, por padrão, que os campos que não foram especificados no YAML original sempre aparecem na especificação do recurso do Kubernetes. Isso significa que, quando você faz kubectl get <resource kind> <resource name> -oyaml, muitos campos na especificação do recurso não estão no YAML aplicado.

Por exemplo, suponha que o esquema CRD permita especificar dois campos chamados foo e bar na especificação, enquanto o arquivo YAML aplicado tem apenas foo especificado:

spec:
  foo: "foo"

Você perceberá que outro campo chamado bar aparece no recurso do Kubernetes se o YAML for aplicado com sucesso e o recurso estiver UpToDate:

spec:
  foo: "foo"
  bar: "bar"

Devido à complexidade da interação entre o Config Connector e as APIs do Google Cloud, é recomendável alterar esse comportamento padrão e pular o preenchimento da especificação de recurso com campos não especificados.

Pular o preenchimento de campos não especificados na especificação

Ao criar seu arquivo YAML, é possível especificar o valor da anotação cnrm.cloud.google.com/state-into-spec como absent. Isso pula o preenchimento de campos não especificados na especificação de recursos do Kubernetes:

metadata:
  annotations:
    cnrm.cloud.google.com/state-into-spec: absent

Essa anotação tem um valor padrão de merge se não for especificado, o que significa que o Config Connector preenche todos os campos não especificados na especificação. Essa anotação é imutável, ou seja, não é possível atualizar o valor da anotação de um recurso existente do Config Connector.

Se você já tiver criado o recurso, mas quiser alterar o valor dessa anotação para um comportamento de preenchimento diferente, siga estas etapas:

1. Edite e adicione a anotação cnrm.cloud.google.com/deletion-policy: abandon ao recurso atual do Kubernetes para garantir que a exclusão na próxima etapa não exclua o recurso subjacente do Google Cloud.

2. Excluir o recurso do cluster do Kubernetes.

3. Adicione a anotação cnrm.cloud.google.com/state-into-spec: absent ao YAML do recurso.

4. Opcional: remova cnrm.cloud.google.com/deletion-policy: abandon do YAML.

5. Aplique o YAML atualizado.

Para explicar melhor a diferença introduzida por essa anotação, suponha que há uma especificação com o esquema abaixo:

foo1: string
foo2: string
bars:
- bar:
    br1: string
    br2: string
barz:
  bz1: string
  bz2: string

Além disso, suponha que você tenha especificado a especificação no YAML como:

spec:
  foo1: "foo1"
  bars:
  - br1: "1_br1"
  - br1: "2_br1"
  barz:
    bz1: "bz1"

Assim, por padrão, a especificação preenchida no recurso do Kubernetes criado será:

spec:
  foo1: "foo1"
  foo2: "foo2"
  bars:
  - br1: "1_br1"
    br2: "1_br2"
  - br1: "2_br1"
    br2: "2_br2"
  barz:
    bz1: "bz1"
    bz2: "bz2"

Se você definir cnrm.cloud.google.com/state-into-spec: absent, a especificação final no recurso do Kubernetes criado será:

spec:
  foo1: "foo1"
  bars:
  - br1: "1_br1"
  - br1: "2_br1"
  barz:
    bz1: "bz1"

Quando usar cnrm.cloud.google.com/state-into-spec: absent

Existem alguns cenários comuns em que é recomendável definir cnrm.cloud.google.com/state-into-spec: absent.

Gerenciar campos não especificados em uma lista externamente

O Config Connector trata todos os campos de lista nas especificações de recursos como campos atômicos. Como resultado, por padrão, a alteração feita em um subcampo na lista de fora do Config Connector será revertida pelo Config Connector. No entanto, é possível usar essa anotação para permitir que o Config Connector cancele o gerenciamento de subcampos na lista. Para mais informações, consulte Comportamento para campos de lista na especificação do recurso.

Resolver a luta entre as ferramentas de gerenciamento de configuração e o Config Connector

Se você estiver usando ferramentas de gerenciamento de configuração, como o Config Sync ou o Argo CD, poderá notar uma divergência entre a ferramenta de gerenciamento de configuração e o Config Connector. Um exemplo é o erro KNV2005, explicado no guia de solução de problemas. A causa raiz desses tipos de problemas é porque:

1. O Config Connector preencherá e os valores não especificados na lista na especificação serão preenchidos. O spec.bars[0].br2 é um exemplo.
2. As ferramentas de gerenciamento de configuração e o Config Connector tratam os campos de lista como atômicos. Assim, o spec.bars[0].br2 adicionado é tratado como um desvio pelas ferramentas de gerenciamento de configuração e será removido para corrigir o drift.

Para resolver esses problemas, defina cnrm.cloud.google.com/state-into-spec: absent para que o Config Connector não adicione o campo spec.bars[0].br2 não especificado à especificação.

Resolver problemas de simetria GET/PUT

A simetria GET/PUT se refere a um princípio de design da API REST. Especificamente, isso significa que, quando uma resposta GET é enviada como uma solicitação PUT para o mesmo URL, o resultado esperado é uma resposta HTTP 200 OK sem alteração no estado do recurso REST subjacente.

Os campos não especificados preenchidos pelo Config Connector na especificação do recurso são resultado de uma solicitação GET. Isso significa que, em reconciliações futuras, o Config Connector poderá enviar uma solicitação PUT/PATCH para a API do Google Cloud subjacente, com esses valores de campo não especificados aprendidos com a solicitação GET. Isso geralmente não é um problema, mas é possível que algumas APIs do Google Cloud recusem a solicitação PUT/PATCH devido a esses valores de campo não especificados. No mesmo exemplo, a spec.barz.bz2 preenchida com o valor "bz2" pode resultar em um erro de cliente HTTP 400 ou outras respostas inesperadas se a implementação da API violar o princípio de simetria GET/PUT.

Para evitar essa categoria de problemas, experimente definir cnrm.cloud.google.com/state-into-spec: absent e verificar se os erros durante a reconciliação vão desaparecer.

Quando evitar cnrm.cloud.google.com/state-into-spec: absent

Evite definir cnrm.cloud.google.com/state-into-spec: absent se sua solução depender dos valores preenchidos em campos não especificados. Por exemplo, se você estiver usando um recurso ComputeAddress e precisar do valor spec.address gerado pelo servidor, que pode ser um campo não especificado no YAML original, não use essa anotação, porque ela pulará o preenchimento do valor de spec.address na especificação de recursos do Kubernetes.