Como atualizar uma implantação

Depois de criar uma implantação, você poderá atualizá-la à medida que o aplicativo ou o serviço mudar. Você pode usar o Deployment Manager para atualizar uma implantação:

  • adicionando ou removendo recursos de uma implantação;
  • atualizando as propriedades de recursos existentes em uma implantação.

Uma única atualização pode conter qualquer combinação dessas alterações. Por exemplo, é possível fazer alterações nas propriedades dos recursos atuais e adicionar novos recursos na mesma solicitação. Atualize sua implantação seguindo estas etapas:

  1. Faça alterações ou crie um arquivo de configuração com as alterações desejadas.
  2. Se quiser, escolha as políticas para usar nas atualizações ou use as políticas padrão.
  3. Faça a solicitação de atualização para o Deployment Manager.

Antes de começar

Preparar a atualização

Antes de atualizar a implantação, siga estas diretrizes para preparar a atualização:

  • Caso esteja atualizando a implantação para adicionar novos recursos ao projeto, verifique se os recursos já existem.

    Por padrão, se um recurso que você quer adicionar já existir no seu projeto, ele será adquirido pela implantação sem criar um novo. Se você não quiser adquirir um recurso existente, altere a política a ser usada na atualização.

    Para mais informações sobre as políticas que são possíveis usar durante a atualização de implantações, consulte Políticas para adicionar recursos.

  • Caso esteja atualizando a implantação para substituir um recurso, verifique suas dependências.

    Se você quiser substituir um recurso da implantação, é preciso primeiro certificar-se de que a exclusão não causará um ciclo de implantação. Um ciclo de implantação ocorre quando um recurso depende de si mesmo, direta ou indiretamente. Por exemplo, veja a seguinte implantação:

    resources:
- name: vm-a
  properties:
    zone: us-central1-f
    ...
    metadata:
      dependsOn:
      - vm-depends-on

# The second VM
- name: vm-depends-on
  properties:
    zone: $(ref.vm-a.zone)
    ...

    Nesta implantação, para vm-a, a instrução dependsOn requer que vm-depends-on precise ser criado antes de vm-a. No entanto, vm-depends-on usa uma referência à zona para vm-a, que exige que vm-a seja criado antes de vm-depends-on. Em um cenário assim, as dependências se repetem e a implantação falha.

    Se você tiver recursos que dependem de outros recursos e vice-versa, a substituição deles poderá causar um ciclo de implantação.

    Por exemplo, suponha que uma implantação tem um disco permanente chamado disk-a, uma VM chamada vm-a e um grupo de instâncias chamado ig-a. A configuração de vm-a inclui uma referência a disk-a e a configuração de ig-a inclui uma referência a vm-a. Em uma configuração atualizada, remova vm-a e substitua por vm-b. Em um cenário assim, resolver as dependências de vm-a e vm-b pode causar um ciclo de implantação e falha da implantação.

    Para evitar ciclos de implantação quando você quiser substituir um recurso em uma cadeia de dependências, siga um destes procedimentos:

    • Remova as dependências do recurso que você quer substituir, seja removendo a cláusula dependsOn, ou removendo ou alterando referências a outros recursos. Depois de atualizar a implantação com essas alterações, faça outra atualização para substituir o recurso.

    • Exclua a cadeia de recursos dependentes e atualize a implantação. Em seguida, na próxima atualização, recrie os recursos que você quer usar.

  • Verifique se há uma API de base compatível com a atualização.

    O Deployment Manager usa as APIs de cada serviço para criar e modificar as implantações. Para verificar se a solicitação pode ser concluída pelo Deployment Manager, revise a documentação da API do serviço do Cloud Platform referente aos recursos que você quer atualizar.

    Por exemplo, para atualizar um conjunto de dados do BigQuery na implantação, consulte os métodos disponíveis na referência da API Datasets. Os métodos incluem um método update, que indica que é possível atualizar o conjunto de dados usando o Deployment Manager.

    Algumas APIs têm métodos personalizados para atualizar recursos. Por exemplo, o Compute Engine oferece um método personalizado para atualizar os metadados de uma instância chamado setMetadata. Nesses casos, o Deployment Manager tenta usar os métodos personalizados.

  • Verifique se os recursos que você está atualizando são mutáveis.

    Alguns recursos são imutáveis após a criação e não podem ser atualizados. Para determinar se um recurso é imutável, consulte a referência da API do recurso. Normalmente, um recurso imutável não tem um método de API update ou um método personalizado para atualizar as propriedades do recurso.

Limitações

  • Para cada implantação, você pode aplicar uma atualização por vez. Se uma atualização já estiver em andamento, será preciso interromper a atualização atual antes de iniciar uma nova atualização.

  • Se você tiver modificado um recurso em uma implantação sem usar o Deployment Manager, como no console do Google Cloud ou gcloud, você poderá encontrar erros ou problemas inesperados ao tentar modificar o recurso em uma atualização.

Fazer alterações na configuração

Se você salvou uma configuração existente, faça alterações nela e use-a na solicitação de atualização.

Se você não tiver uma configuração existente salva, crie uma nova. Para etapas de criação de um arquivo de configuração, consulte "Configurações".

O Deployment Manager compara a configuração fornecida em sua solicitação de atualização ao manifesto anterior e usa as diferenças para atualizar sua implantação.

Por exemplo, a seguinte tabela mostra duas configurações: uma descreve uma implantação atual e outra descreve o estado atualizado pretendido da implantação. Você fornece a configuração atualizada, e o Deployment Manager avalia as diferenças e faz as atualizações apropriadas.

Neste exemplo atualizamos um recurso de instância existente para incluir alguns metadados personalizados e também adicionamos um novo recurso de máquina virtual à implantação. As partes em negrito são as diferenças entre os modelos.

Modelo atual Modelo atualizado 
resources:
- name: vm-created-by-cloud-config
  type: compute.v1.instance
  properties:
    zone: us-central1-a
    machineType: machine-type-url
    disks:
    - deviceName: boot
      type: PERSISTENT
      boot: true
      autoDelete: true
      initializeParams:
        diskName: disk-created-by-cloud-config
        sourceImage: image-url
    networkInterfaces:
    - network: network-url
 
resources:
- name: vm-created-by-cloud-config
  type: compute.v1.instance
  properties:
    zone: us-central1-a
    machineType: machine-type-url
    disks:
    - deviceName: boot
      type: PERSISTENT
      boot: true
      initializeParams:
        diskName: disk-created-by-cloud-config
        sourceImage: image-url
    networkInterfaces:
    - network: network-url
    metadata:
      items:
      - key: 'foo'
        value: 'bar'
      - key: 'dev'
        value: 'vm'

- name: a-new-vm
  type: compute.v1.instance
  properties:
    zone: us-central1-a
    machineType: machine-type-url
      - deviceName: boot
      type: PERSISTENT
      boot: true
      autoDelete: false
      initializeParams:
        diskName: a-new-vm-disk
        sourceImage: image-url
    networkInterfaces:
    - network: network-url

Determinar as políticas que serão usadas na atualização (opcional)

Em seguida, determine quais políticas você quer usar na atualização. A política determina como os recursos são atualizados quando você atualiza a implantação.

O Deployment Manager usa estas políticas padrão:

  • A política padrão para adicionar recursos é CREATE_OR_ACQUIRE.
  • A política padrão para remover recursos é DELETE.
  • A política padrão para atualizar recursos é UPDATE.

Para informações sobre cada política, leia as seções abaixo.

Políticas para adicionar recursos

Ao adicionar recursos, é possível criar um novo e adicioná-lo a uma implantação ou adquirir um recurso atual:

  • CREATE_OR_ACQUIRE - [Padrão] o Deployment Manager adquire recursos que existem no projeto ou cria recursos caso eles não existam. Para adquirir um recurso, o Deployment Manager verifica sua configuração para as propriedades do recurso que você está tentando criar. Se houver um recurso atual com as mesmas propriedades, o Deployment Manager adquirirá esse recurso como parte da implantação.

    As propriedades que o Deployment Manager verifica dependem do tipo de recurso que você está criando e podem incluir:

    • O name do recurso
    • O type do recurso
    • O zone ou region do recurso, se aplicável

    As propriedades fazem parte do URL da solicitação da API GET para o recurso. Para saber quais propriedades o Deployment Manager usa para adquirir um recurso, consulte a documentação da API para o método GET do recurso. Por exemplo, para instâncias do Compute Engine, o URL de solicitação para o método instances.get inclui o resourceId (name na sua configuração), zone e project.

  • CREATE: o Deployment Manager cria recursos que não existem. Se algum dos recursos da sua configuração já existir no projeto, a implantação falhará.

  • ACQUIRE - o Deployment Manager adquire recursos que já existem usando os mesmos critérios que CREATE_OR_ACQUIRE.

    Use a política ACQUIRE se você já tiver vários recursos em seu projeto e quiser gerenciá-los juntos, como uma única implantação.

    Em seu modelo ou sua configuração, você precisa informar as propriedades necessárias para esses recursos como se eles estivessem sendo criados. Se algum dos recursos em sua configuração não existir no projeto, a implantação falhará.

Políticas para remover recursos

Forneça uma das seguintes políticas para remover recursos:

  • DELETE - [Padrão] remove da implantação todas as referências ao recurso e exclui o recurso subjacente. Isso é permanente e não pode ser desfeito, mas é possível recriar um novo recurso com as mesmas propriedades.

  • ABANDON: remove da implantação todas as referências ao recurso, mas não exclui o recurso subjacente. Por exemplo, o abandono de uma instância significa que ela foi removida de uma implantação, mas a instância ainda existe para você usar.

    A política ABANDON se aplica somente quando você exclui recursos inteiros, não quando você exclui as propriedades de um recurso ou atualiza um recurso com novas propriedades. Se você quer preservar as propriedades de um recurso, inclua o recurso com todas as suas propriedades originais na configuração atualizada. Se você estiver usando um novo arquivo de configuração para a atualização, recomendamos copiar a definição do recurso da sua configuração original.

Políticas para atualizar um recurso atual

Se houver um método UPDATE para atualizar recursos existentes, o Deployment Manager vai usá-lo.

Caso contrário, se houver um método personalizado, o Deployment Manager usará esse método. O Deployment Manager é compatível com métodos personalizados que usam o verbo set. Por exemplo, setMetadata() é um método personalizado válido, mas addAccessConfigs() não é.

Visualizar uma configuração atualizada (opcional)

É possível visualizar a atualização que você quer fazer antes de confirmar qualquer alteração, com a Google Cloud CLI ou a API. O serviço do Deployment Manager visualiza a configuração expandindo a configuração completa e criando recursos de "shell".

O Deployment Manager não instancia recursos reais quando você visualiza uma configuração, dando a oportunidade de ver a implantação antes de confirmá-la.

gcloud

Com a Google Cloud CLI, faça uma solicitação update com o parâmetro --preview:

gcloud deployment-manager deployments update example-deployment \
    --config configuration-file.yaml \
    --preview

API

Na API, crie uma solicitação PUT() com uma implantação atual e forneça o parâmetro de consulta preview=true. O corpo da solicitação precisa conter os campos intent, target e name. Insira o nome da implantação no URL e no corpo da solicitação.

Por exemplo, a seguinte solicitação de API visualiza uma atualização simples:

PUT https://www.googleapis.com/deploymentmanager/v2/projects/myproject/global/deployments/example-deployment?preview=true

{
 "target": {
  "config": {
   "content": "resources:\n- name: vm-created-by-cloud-config\n  type: compute.v1.instance\n  properties:\n    zone: us-central1-a\n    machineType: https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/machineTypes/n1-standard-1\n    disks:\n    - deviceName: boot\n      type: PERSISTENT\n      boot: true\n      autoDelete: true\n      initializeParams:\n        diskName: disk-created-by-cloud-config\n        sourceImage: https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-9-stretch-v20180716\n    networkInterfaces:\n    - network: https://www.googleapis.com/compute/v1/projects/myproject/global/networks/default"
  }
 },
 "name": "example-deployment"
}

Depois de visualizar uma implantação, é possível implantar a configuração totalmente fazendo a mesma solicitação PUT(), omitindo a configuração e o parâmetro de consulta preview. O Deployment Manager usa a visualização mais recente para executar a atualização. Por exemplo:

gcloud deployment-manager deployments update example-deployment

Para ver as etapas de uma solicitação de atualização, consulte Fazer a solicitação de atualização.

Se você decidir não continuar a atualização, cancele a visualização atual antes de fazer outra atualização ou solicitação de visualização.

Cancelar uma visualização

Depois de visualizar uma atualização, você precisará decidir se quer continuá-la. Se não quiser continuar ou se quiser usar um arquivo de configuração diferente para atualizar a implantação, cancele a visualização atual.

gcloud

Com a Google Cloud CLI, faça uma solicitação deployments cancel-preview:

gcloud deployment-manager deployments cancel-preview my-first-deployment

API

Na API, faça uma solicitação PUT() para o método cancelPreview e forneça a impressão digital de implantação mais recente. Uma impressão digital é um valor gerado aleatoriamente que é alterado a cada solicitação de atualização. Para evitar erros durante a atualização, forneça a impressão digital mais recente com sua solicitação.

Para conseguir a impressão digital mais recente de uma implantação, use o método get() para conseguir uma implantação e procure o valor da impressão digital. O valor da impressão digital tem a seguinte aparência:

"fingerprint": "nU2v7bzeA7gBBI8bdbtmFg=="

A solicitação cancelPreview() é assim:

POST https://www.googleapis.com/deploymentmanager/v2/projects/myproject/global/deployments/example-deployment/cancelPreview

{
 "fingerprint": "nU2v7bzeA7gBBI8bdbtmFg=="
 }

Fazer a solicitação de atualização

Para realizar a atualização:

gcloud

Com a Google Cloud CLI, use o subcomando deployments update, fornecendo uma nova configuração e, opcionalmente, suas políticas de atualização.

gcloud deployment-manager deployments update my-first-deployment \
    --create-policy POLICY \
    --delete-policy POLICY

Omita essa configuração caso você já tenha visualizado uma antes. O Deployment Manager usa a configuração visualizada mais recentemente para realizar a atualização.

gcloud deployment-manager deployments update my-first-deployment

API

Na API, faça uma solicitação update e forneça a impressão digital mais recente da implantação. Uma impressão digital é um valor gerado aleatoriamente que é alterado a cada solicitação de atualização. Para evitar erros durante a atualização, forneça a impressão digital mais recente com sua solicitação.

Para conseguir a impressão digital mais recente de uma implantação, use o método get() para conseguir uma implantação e procure o valor da impressão digital. O valor da impressão digital tem a seguinte aparência:

"fingerprint": "nU2v7bzeA7gBBI8bdbtmFg=="

Em seguida, forneça a impressão digital na solicitação, juntamente com as novas políticas de configuração e atualização. Se você já visualizou a configuração, omita a configuração e as políticas de atualização. O Deployment Manager usa a configuração visualizada mais recentemente para executar a atualização.

Insira o nome da implantação no URL e no corpo da solicitação.

PUT https://www.googleapis.com/deploymentmanager/v2/projects/myproject/global/deployments/example-deployment?createPolicy=ACQUIRE&deletePolicy=ABANDON

{
 "target": {
  "config": {
   "content": "resources:\n- name: vm-created-by-cloud-config\n  type: compute.v1.instance\n  properties:\n    zone: us-central1-a\n    machineType: https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/machineTypes/n1-standard-1\n    disks:\n    - deviceName: boot\n      type: PERSISTENT\n      boot: true\n      autoDelete: true\n      initializeParams:\n        diskName: disk-created-by-cloud-config\n        sourceImage: https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-9-stretch-v20180716\n    networkInterfaces:\n    - network: https://www.googleapis.com/compute/v1/projects/myproject/global/networks/default"
  }
 },
 "name": "example-deployment",
 "fingerprint": "nU2v7bzeA7gBBI8bdbtmFg=="
}

Parar uma atualização

É possível parar uma atualização em andamento usando o método stop() . Isso cancela qualquer progresso de uma determinada atualização, mas não desfaz alterações que já foram feitas.

Caso você esteja tentando cancelar uma visualização, consulte a seção Cancelar uma visualização.

gcloud

Com a Google Cloud CLI, faça uma solicitação deployments stop:

gcloud deployment-manager deployments stop my-first-deployment

API

Na API, faça uma solicitação POST() para o método stop e forneça a propriedade de impressão digital mais recente. Uma impressão digital é um valor gerado aleatoriamente que é alterado a cada solicitação de atualização. Para evitar alterações conflitantes, é preciso fornecer a impressão digital mais recente com sua solicitação para realizar um bloqueio otimista para que apenas uma atualização possa ser feita de cada vez.

Para conseguir a impressão digital mais recente de uma implantação, use o método get() para conseguir uma implantação e procure o valor da impressão digital. O valor da impressão digital tem a seguinte aparência:

"fingerprint": "nU2v7bzeA7gBBI8bdbtmFg=="

A solicitação tem esta aparência:

POST https://www.googleapis.com/deploymentmanager/v2/projects/myproject/global/deployments/example-deployment/stop

{
 "fingerprint": "nU2v7bzeA7gBBI8bdbtmFg=="
 }

A seguir