Atualizar uma implementação

Depois de criar uma implementação, pode atualizá-la à medida que a sua aplicação ou serviço muda. Pode usar o Deployment Manager para atualizar uma implementação:

  • Adicionar ou remover recursos de uma implementação.
  • Atualizar as propriedades dos recursos existentes numa implementação.

Uma única atualização pode conter qualquer combinação destas alterações. Por exemplo, pode alterar as propriedades dos recursos existentes e adicionar novos recursos no mesmo pedido. Atualize a implementação seguindo estes passos:

  1. Fazer alterações ou criar um ficheiro de configuração com as alterações pretendidas.
  2. Opcionalmente, escolha as políticas a usar para as suas atualizações ou use as políticas predefinidas.
  3. Faça o pedido de atualização ao Deployment Manager.

Antes de começar

Prepare a atualização

Antes de atualizar a implementação, use estas diretrizes para preparar a atualização:

  • Se estiver a atualizar a sua implementação para adicionar novos recursos ao seu projeto, verifique se os recursos já existem.

    Por predefinição, se um recurso que quer adicionar já existir no seu projeto, é adquirido pela implementação, sem criar um novo recurso. Se não quiser adquirir um recurso existente, tem de alterar a política a usar para a atualização.

    Para ver informações sobre as políticas que pode usar ao atualizar implementações, consulte Políticas para adicionar recursos.

  • Se estiver a atualizar a implementação para substituir um recurso, verifique as respetivas dependências

    Se quiser substituir um recurso da sua implementação, primeiro tem de se certificar de que a eliminação do mesmo não causa um ciclo de implementação. Um ciclo de implementação ocorre quando um recurso depende de si próprio, direta ou indiretamente. Por exemplo, considere a seguinte implementaçã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 implementação, para vm-a, a declaração dependsOn requer que vm-depends-on seja criado antes de vm-a. No entanto, vm-depends-on usa uma referência à zona para vm-a, o que requer que vm-a seja criado antes de vm-depends-on. Neste cenário, as dependências estão num ciclo, e a implementação falha.

    Se tiver um recurso que dependa de outros recursos e do qual outros recursos dependam, a substituição desse recurso pode causar um ciclo de implementação.

    Por exemplo, considere que uma implementação tem um disco persistente denominado disk-a, uma VM denominada vm-a e um grupo de instâncias denominado 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. Numa configuração atualizada, quer remover vm-a e substituí-lo por vm-b. Neste cenário, a resolução das dependências para vm-a e vm-b pode causar um ciclo de implementação, e a sua implementação falha.

    Para evitar ciclos de implementação quando quiser substituir um recurso numa cadeia de dependências, faça uma das seguintes ações:

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

    • Elimine a cadeia de recursos dependentes e atualize a implementação. Em seguida, na atualização seguinte, recrie os recursos que quer usar.

  • Certifique-se de que existe uma API subjacente que suporta a sua atualização.

    O Deployment Manager usa as APIs de cada serviço para criar e modificar as suas implementações. Para verificar se o seu pedido pode ser concluído pelo Deployment Manager, reveja a documentação da API do serviço da Cloud Platform para os recursos que quer atualizar.

    Por exemplo, se quiser atualizar um conjunto de dados do BigQuery na sua implementação, consulte os métodos disponíveis na referência da API Datasets. Os métodos incluem um método update, que indica que pode atualizar o conjunto de dados através do Gestor de Implementações.

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

  • Certifique-se de que os recursos que está a atualizar 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 para o recurso. Normalmente, um recurso imutável não tem um método de API update nem um método personalizado para atualizar as propriedades do recurso.

Limitações

  • Para cada implementação, pode aplicar uma atualização de cada vez. Se já estiver em curso uma atualização, tem de parar a atualização atual antes de iniciar uma nova atualização.

  • Se modificou um recurso numa implementação sem usar o Deployment Manager, como na Google Cloud consola ou gcloud, pode ver erros ou problemas inesperados quando tenta modificar o recurso numa atualização.

Faça alterações à sua configuração

Se guardou uma configuração existente, faça alterações à configuração e use-a no seu pedido de atualização.

Se não tiver uma configuração guardada, crie uma nova configuração. Para ver os passos para criar um ficheiro de configuração, leia o artigo Configurações.

O Deployment Manager compara a configuração que fornece no pedido de atualização com o manifesto anterior e usa as diferenças para atualizar a implementação.

Por exemplo, a tabela seguinte mostra duas configurações: uma descreve uma implementação existente e a outra descreve o estado atualizado pretendido da implementação. Fornece a configuração atualizada e o Deployment Manager avalia as diferenças e faz as atualizações adequadas.

Este exemplo atualiza um recurso de instância existente para incluir alguns metadados personalizados e também adiciona um novo recurso de máquina virtual à implementação. As partes em negrito são 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

(Opcional) Determine as políticas a usar para a atualização

Em seguida, determine as políticas que quer usar para a atualização. A política determina como os seus recursos são atualizados quando atualiza a implementação.

O Deployment Manager usa estas políticas predefinidas:

  • A política predefinida para adicionar recursos é CREATE_OR_ACQUIRE.
  • A política predefinida para remover recursos é DELETE.
  • A política predefinida para atualizar recursos é UPDATE.

Para ver informações sobre cada política, reveja as secções abaixo.

Políticas para adicionar recursos

Quando adiciona recursos, pode optar por criar um novo recurso e adicioná-lo a uma implementação ou pode adquirir um recurso existente:

  • CREATE_OR_ACQUIRE - [Predefinição] O Deployment Manager adquire recursos que existem no projeto ou cria recursos se não existirem. Para adquirir um recurso, o Deployment Manager verifica a sua configuração para as propriedades do recurso que está a tentar criar. Se existir um recurso com as mesmas propriedades, o Deployment Manager adquire esse recurso como parte da sua implementação.

    As propriedades que o Deployment Manager verifica dependem do tipo de recurso que está a criar e podem incluir:

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

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

  • CREATE - O Deployment Manager cria recursos que não existem. Se algum dos recursos na sua configuração já existir no projeto, a implementação falha.

  • ACQUIRE - O Deployment Manager adquire recursos já existentes, usando os mesmos critérios que CREATE_OR_ACQUIRE.

    Use a política ACQUIRE se já tiver vários recursos no seu projeto e quiser geri-los em conjunto como uma única implementação.

    No modelo ou na configuração, tem de fornecer as propriedades necessárias para estes recursos como se os estivesse a criar. Se algum dos recursos na sua configuração não existir no projeto, a implementação falha.

Políticas para remover recursos

Indique uma das seguintes políticas para remover recursos:

  • DELETE - [Predefinição] Esta opção remove todas as referências ao recurso da implementação e elimina o recurso subjacente. Esta ação é definitiva e não pode ser anulada, mas pode recriar um novo recurso com as mesmas propriedades.

  • ABANDON: isto remove todas as referências ao recurso da implementação, mas não elimina o recurso subjacente. Por exemplo, abandonar uma instância significa que é removida de uma implementação, mas a instância continua a existir para sua utilização.

    A política ABANDON aplica-se apenas quando elimina recursos completos e não quando elimina as propriedades de um recurso ou atualiza um recurso com novas propriedades. Se quiser preservar as propriedades de um recurso, tem de incluir o recurso com todas as respetivas propriedades originais na configuração atualizada. Se estiver a usar um novo ficheiro de configuração para a atualização, recomendamos que copie a definição do recurso da configuração original.

Políticas para atualizar um recurso existente

Se existir um método UPDATE para atualizar recursos existentes, o Deployment Manager usa esse método.

Caso contrário, se existir um método personalizado, o Deployment Manager usa o método personalizado. O Deployment Manager suporta métodos personalizados que usam o verbo set. Por exemplo, setMetadata() é um método personalizado válido, mas addAccessConfigs() não é.

(Opcional) Pré-visualize uma configuração atualizada

Pode pré-visualizar a atualização que quer fazer antes de confirmar quaisquer alterações com a CLI Google Cloud ou a API. O serviço Deployment Manager apresenta uma pré-visualização da configuração expandindo a configuração completa e criando recursos "shell".

O Deployment Manager não instancia recursos reais quando pré-visualiza uma configuração, o que lhe dá a oportunidade de ver a implementação antes de a confirmar.

gcloud

Com a Google Cloud CLI, faça um pedido update com o parâmetro --preview:

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

API

Na API, crie um pedido PUT() com uma implementação existente e forneça o parâmetro de consulta preview=true. O corpo do pedido tem de conter os campos intent, target e name. Indique o nome da implementação no URL e no corpo do pedido.

Por exemplo, o pedido de API seguinte pré-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 pré-visualizar uma implementação, pode implementar totalmente a configuração fazendo o mesmo pedido PUT(), omitindo a configuração e o parâmetro de consulta preview. O Deployment Manager usa a última pré-visualização para fazer a atualização. Por exemplo:

gcloud deployment-manager deployments update example-deployment

Para ver os passos para fazer um pedido de atualização, consulte a secção Faça o pedido de atualização.

Se decidir não continuar com a atualização, cancele a pré-visualização atual antes de fazer outro pedido de atualização ou pré-visualização.

Cancele uma pré-visualização

Depois de pré-visualizar uma atualização, tem de decidir se quer continuar com a atualização. Se não quiser continuar ou se quiser usar um ficheiro de configuração diferente para atualizar a implementação, cancele a pré-visualização atual.

gcloud

Com a CLI do Google Cloud, faça um pedido deployments cancel-preview:

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

API

Na API, faça um pedido PUT() ao método cancelPreview e forneça a impressão digital de implementação mais recente. Uma impressão digital é um valor gerado aleatoriamente que muda com cada pedido de atualização. Para evitar erros durante a atualização, forneça a impressão digital mais recente com o seu pedido.

Para obter a impressão digital mais recente de uma implementação, use o método get() para obter uma implementação e procure o valor da impressão digital. O valor da impressão digital tem o seguinte aspeto:

"fingerprint": "nU2v7bzeA7gBBI8bdbtmFg=="

O seu pedido cancelPreview() tem o seguinte aspeto:

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

{
 "fingerprint": "nU2v7bzeA7gBBI8bdbtmFg=="
 }

Faça o pedido de atualização

Para fazer a atualização:

gcloud

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

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

Se tiver pré-visualizado uma configuração anteriormente, omita a configuração e o Deployment Manager usa a última configuração pré-visualizada para fazer a atualização.

gcloud deployment-manager deployments update my-first-deployment

API

Na API, faça um pedido update e faculte a impressão digital de implementação mais recente. Uma impressão digital é um valor gerado aleatoriamente que muda com cada pedido de atualização. Para evitar erros durante a atualização, forneça a impressão digital mais recente com o seu pedido.

Para obter a impressão digital mais recente de uma implementação, use o método get() para obter uma implementação e procure o valor da impressão digital. O valor da impressão digital tem o seguinte aspeto:

"fingerprint": "nU2v7bzeA7gBBI8bdbtmFg=="

Em seguida, forneça a impressão digital no seu pedido, juntamente com a nova configuração e as políticas de atualização. Se tiver pré-visualizado anteriormente a configuração, omita a configuração e atualize as políticas. O Deployment Manager usa a última configuração pré-visualizada para fazer a atualização.

Indique o nome da implementação no URL e no corpo do pedido.

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=="
}

Pare uma atualização

Pode parar uma atualização em curso através do stop(). method. Esta ação cancela qualquer progresso adicional de uma atualização específica, mas não anula nenhuma alteração já feita.

Se estiver a tentar cancelar uma pré-visualização, consulte a secção Cancelar uma pré-visualização.

gcloud

Com a CLI do Google Cloud, faça um pedido deployments stop:

gcloud deployment-manager deployments stop my-first-deployment

API

Na API, faça um pedido POST() ao método stop e faculte a propriedade de impressão digital mais recente. Uma impressão digital é um valor gerado aleatoriamente que muda com cada pedido de atualização. Para evitar alterações em conflito, tem de fornecer a impressão digital mais recente com o seu pedido para efetuar o bloqueio otimista, de modo que só seja possível fazer uma atualização de cada vez.

Para obter a impressão digital mais recente de uma implementação, use o método get() para obter uma implementação e procure o valor da impressão digital. O valor da impressão digital tem o seguinte aspeto:

"fingerprint": "nU2v7bzeA7gBBI8bdbtmFg=="

O seu pedido tem o seguinte aspeto:

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

{
 "fingerprint": "nU2v7bzeA7gBBI8bdbtmFg=="
 }

O que se segue?