Como executar scripts de inicialização

VMs Linux VMs Windows

O Compute Engine permite criar e executar seus próprios scripts de inicialização nas instâncias de máquina virtual (VM) para realizar tarefas automatizadas sempre que a instância for inicializada. Os scripts de inicialização podem executar ações como instalar software, executar atualizações, ativar serviços e qualquer outra tarefa definida no script.

Veja a seguir um exemplo de um script de inicialização que instala e inicia um servidor Apache:

#! /bin/bash
apt update
apt -y install apache2
cat <<EOF > /var/www/html/index.html
<html><body><h1>Hello World</h1>
<p>This page was created from a startup script.</p>
</body></html>
EOF

Para especificar um script de inicialização, use chaves de metadados de scripts de inicialização com o servidor de metadados. Use o Console do Google Cloud, a ferramenta de linha de comando gcloud ou a API Compute Engine para fornecer um script de inicialização.

Antes de começar

Para usar os exemplos de linha de comando deste guia, siga estas etapas:
1. Instale ou atualize a ferramenta de linha de comando gcloud para a versão mais recente.
2. Defina uma região e uma zona padrão.
Para usar os exemplos de API deste guia, configure o acesso à API.
Entenda o que é o servidor de metadados.
Configure seu editor de texto para salvar texto ASCII com terminações de linha Unix.

Permissões exigidas para a tarefa

Para executar esta tarefa, é preciso ter a permissão a seguir:

Todas as permissões necessárias para criar uma nova instância
compute.instances.setMetadata na instância

Como executar um script de inicialização

Quando a rede estiver disponível, a VM sempre executará scripts de inicialização da seguinte maneira:

Para VMs do Linux, usando o usuário root.
Para VMs do Windows, usando a conta System.

Um script de inicialização pode ser um arquivo de qualquer tipo. Se houver um script de inicialização, o Compute Engine fará o seguinte:

Copiará o script de inicialização em um arquivo local na instância
Definirá as permissões de execução no arquivo
Executará o arquivo

Por exemplo, é possível fornecer um script Python em vez de um script bash. Lembre-se de que o Compute Engine executa o script na íntegra, independentemente do tipo.

Para executar um script que não seja bash, adicione um shebang (uma linha que começa com #!) na parte superior do arquivo. Isso informa ao sistema operacional qual interpretador usar. Por exemplo, se você usar um script Python, é possível adicionar a seguinte linha de Shebang:

#! /usr/bin/python

Como usar um script de inicialização local

Os scripts de inicialização local ficam localizados no seu computador. Para usar um script de inicialização local, passe um arquivo de script de inicialização local para a instância ou forneça o conteúdo de um script de inicialização diretamente ao servidor de metadados. Os exemplos das subseções a seguir mostram como adicionar metadados de script de inicialização por meio de um arquivo local ou por inserção direta.

Os scripts de inicialização local estão sujeitos ao limite de comprimento do valor de metadados de 256 KB. Se o script de inicialização exceder esse limite, não será possível carregá-lo localmente. Em vez disso, salve o arquivo no Cloud Storage e especifique o URL do script durante a criação da instância. Para mais informações, consulte Como fornecer um script de inicialização armazenado no Cloud Storage.

Fornecer um arquivo de script de inicialização

Só é possível passar um arquivo de script de inicialização local usando a ferramenta de linha de comando gcloud. Inclua a sinalização --metadata-from-file, seguida por um par de chaves de metadados, startup-script=PATH_TO_FILE, substituindo PATH_TO_FILE por um caminho relativo para o script de inicialização:

gcloud compute instances create example-instance \
  --metadata-from-file startup-script=examples/scripts/install.sh

Fornecer conteúdo do script de inicialização diretamente

Como alternativa, é possível usar o Console do Google Cloud, a ferramenta de linha de comando gcloud ou a API do Compute Engine para digitar ou colar diretamente o conteúdo do script de inicialização.

Console

No Console do Cloud, especifique um script de inicialização diretamente na seção Script de inicialização:

No Console do Cloud, acesse a página Instâncias de VM.
Acessar instâncias de VM
Clique em Criar instância.
Na página Criar uma nova instância, preencha as propriedades da sua instância. Para opções avançadas de configuração, expanda a seção Gerenciamento, segurança, discos, rede, locatário único.

Na seção Automação, em Script de inicialização, forneça o conteúdo do script de inicialização.
Clique em Criar para criar a instância.

gcloud

Com a ferramenta de linha de comando gcloud, use a sinalização --metadata para fornecer o conteúdo do script de inicialização usando o par de chave-valor startup-script=contents, substituindo contents pelo conteúdo do script de inicialização.

Por exemplo, o comando a seguir cria uma instância que, na inicialização, executa algumas atualizações do sistema, instala o Apache e inicia uma página da Web simples. Execute esse comando e acesse o endereço IP externo da instância para ver o conteúdo da página index.html.

Em um computador com Linux, execute o comando da seguinte maneira:

gcloud compute instances create example-instance --tags http-server \
  --metadata startup-script='#! /bin/bash
# Installs apache and a custom homepage
  apt update
  apt -y install apache2
  cat <<EOF > /var/www/html/index.html
  <html><body><h1>Hello World</h1>
  <p>This page was created from a start up script.</p>
  </body></html>
  EOF'

Se você estiver em uma área de trabalho do Windows, execute este comando em um terminal cmd:

gcloud compute instances create example-instance --tags http-server \
  --metadata startup-script="
  apt update;
  apt -y install apache2;
  echo \"This page was created from a start up script.\" ^> /var/www/html/index.html"

Da mesma forma, se você estiver usando o PowerShell, será possível executar esse comando usando o caractere especial stop parsing (--%) para transmitir um comando exato para a ferramenta gcloud:

gcloud --% compute instances create example-instance --tags http-server \
  --metadata startup-script="
  apt update;
  apt -y install apache2;
  echo \"This page was created from a start up script.\" ^> /var/www/html/index.html"

API

Na API, forneça um script de inicialização como parte da propriedade de metadados na solicitação, usando startup-script como chave de metadados:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances

{
  ...
  "metadata": {
    "items": [
      {
       "key": "startup-script",
       "value": "#! /bin/bash\n\n# Installs apache and a custom homepage\napt update\napt -y install apache2\ncat <<EOF > /var/www/html/index.html\n<html><body><h1>Hello World</h1>\n<p>This page was created from a start up script.</p>\n</body></html>"
      }
    ]
  }
  ...
}

Fornecer um script de inicialização para instâncias do Windows

É possível executar scripts de inicialização em instâncias do Windows usando chaves de metadados exclusivas e específicas do Windows. Escolha uma das chaves de metadados especializados listadas na tabela a seguir. Cada chave de metadados precisa corresponder ao tipo de script que você quer executar. Também é possível especificar vários scripts transmitindo chaves de metadados diferentes para a instância. É possível especificar cada chave de metadados somente uma vez para cada instância de VM.

Se você precisar executar manualmente os scripts de inicialização em uma instância de VM depois que ela for iniciada, um administrador poderá fazer isso usando o seguinte comando:

C:\Program Files\Google\Compute Engine\metadata_scripts\run_startup_scripts.cmd

A tabela a seguir mostra os tipos de scripts de inicialização compatíveis, quando eles são executados e qual chave de metadados usar para especificar o script. Para informações sobre como usar essas chaves de metadados, consulte Como usar um script de inicialização local. Esses scripts só serão executados se você preparar a imagem usando o comando GCESysprep.

Tipo de script	Execuções: Durante `GCESysprep`² Antes da inicialização	Execuções: Depois que `GCESysprep`² for concluído Em cada inicialização subsequente
Scripts de inicialização `url`	chave de metadados: `sysprep-specialize-script-url`	chave de metadados: `windows-startup-script-url`
Scripts de inicialização `cmd`	chave de metadados: `sysprep-specialize-script-cmd`	chave de metadados: `windows-startup-script-cmd`
Scripts de inicialização `bat`	chave de metadados: `sysprep-specialize-script-bat`	chave de metadados: `windows-startup-script-bat`
`ps1`¹Scripts de inicialização	chave de metadados: `sysprep-specialize-script-ps1`	chave de metadados: `windows-startup-script-ps1`

¹ Windows PowerShell
² GCESysprep

Como fornecer um script de inicialização armazenado no Cloud Storage

É possível armazenar seu script no Cloud Storage e fornecer o URL para o script ao criar sua instância. Com isso, é possível acessar o script de inicialização de qualquer lugar e também ignorar o limite do servidor de metadados.

Definir permissões de acesso ao script

Antes de usar um script de inicialização do Cloud Storage, você precisa ter permissão para acessar o script. Verifique as configurações de controle de acesso no bucket e no arquivo para garantir que você tenha permissão.

Por padrão, se você for proprietário ou editor de um projeto, será possível acessar arquivos do mesmo projeto, a menos que haja controles de acesso explícitos que proíbam o acesso.

Fornecer um script de inicialização

Crie um bucket. Crie um bucket ou use um já existente. Para mais informações sobre como criar um bucket, consulte Como criar um bucket no Console do Google Cloud ou Como criar um bucket em gsutil.
Faça o upload do arquivo no bucket. Siga as instruções para usar o gsutil ou o Console do Cloud para fazer upload de um objeto.
Forneça o URL para o arquivo de script de inicialização ao criar uma instância.
Console
1. No Console do Google Cloud, acesse a página Instâncias de VM.
  
  Acessar instâncias de VM
2. Clique em Create Instance.
3. Na página Criar uma nova instância, preencha as propriedades da sua instância.
4. Na seção Identidade e acesso à API, selecione uma conta de serviço com acesso de leitura do arquivo do script de inicialização no Cloud Storage. Por exemplo, a conta de serviço precisa ter as permissões do papel Visualizador de objetos do Storage.
5. Expanda a seção Gerenciamento, segurança, discos, rede, locatário único.
6. Na seção Metadados, forneça startup-script-url como a chave de metadados.
7. Na caixa Valor, forneça um URL para o arquivo de script de inicialização, no formato gs://BUCKET/FILE ou https://storage.googleapis.com/BUCKET/FILE.
8. Clique em Criar para criar a instância.
gcloud
Com a ferramenta de linha de comando gcloud, crie uma instância com as sinalizações --scopes e --metadata e especifique a chave startup-script-url. A sinalização --scopes permite que a VM acesse o Cloud Storage para fazer o download do script de inicialização. É possível fornecer o URL do Cloud Storage para o script no formato gs://BUCKET/FILE ou https://storage.googleapis.com/BUCKET/FILE.
```
gcloud compute instances create example-instance --scopes storage-ro \
  --metadata startup-script-url=gs://BUCKET/FILE.sh
```
API
Na API, forneça um script de inicialização como parte da propriedade de metadados na solicitação, usando startup-script-url como chave de metadados. Além disso, forneça uma lista de scopes que inclua um escopo do Cloud Storage para que a VM possa acessar o arquivo do script de inicialização:
```
POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances

{
  ...
  "serviceAccounts": [
    {
      "email": "default",
      "scopes": [
        "https://www.googleapis.com/auth/devstorage.read_only"
      ]
    }
  ],
  "metadata": {
    "items": [
      {
       "key": "startup-script-url",
       "value": "gs://BUCKET/FILE"
      }
    ]
  },
  "tags": {
    "items": []
  },
  "machineType": "zones/us-central1-a/machineTypes/e2-medium",
  "name": "example-instance"
}
```
Windows
Com a ferramenta de linha de comando gcloud, crie uma instância usando as sinalizações --scopes e --metadata e especifique a chave windows-startup-script-url. A sinalização --scopes permite que a VM acesse o Cloud Storage para fazer o download do script de inicialização. É possível fornecer o URL do Cloud Storage para o script no formato gs://BUCKET/FILE ou https://storage.googleapis.com/BUCKET/FILE.
```
gcloud compute instances create example-windows-instance --scopes storage-ro \
  --metadata windows-startup-script-url=gs://BUCKET/FILE.ps1
```

Aplicar um script de inicialização a instâncias em execução

Se houver uma instância em execução, adicione um script de inicialização a ela. Na próxima reinicialização da instância, esse script será executado. O script de inicialização também é executado em todas as reinicializações subsequentes.

Conclua as instruções a seguir para definir um script de inicialização em uma instância em execução:

Console

No Console do Google Cloud, acesse a página Instâncias de VM.

Acessar instâncias de VM
Clique na instância à qual você quer adicionar um script de inicialização.
Na página de detalhes da instância, conclua estas etapas:
1. Clique no botão Editar.
2. Em Metadados personalizados, clique em Adicionar item.
3. Adicione o script de inicialização usando uma das chaves a seguir:
  - startup-script: use essa chave para fornecer diretamente o conteúdo do script de inicialização.
  - startup-script-url: use essa chave para fornecer um URL do Cloud Storage ao arquivo de script de inicialização.

gcloud

Com a ferramenta de linha de comando gcloud, use o comando instances add-metadata para adicionar metadados à instância. Use qualquer uma das chaves de script de inicialização disponíveis:

--metadata startup-script=CONTENTS: use essa chave para fornecer diretamente o conteúdo do script de inicialização.
--metadata startup-script-url=URL: use essa chave para fornecer um URL do Cloud Storage ao arquivo de script de inicialização.
--metadata-from-file startup-script=FILE: forneça um arquivo de script de inicialização armazenado localmente.

Exemplo:

gcloud compute instances add-metadata EXAMPLE_INSTANCE \
  --metadata-from-file startup-script=PATH_TO_FILE

gcloud compute instances add-metadata EXAMPLE_INSTANCE \
  --metadata startup-script-url=gs://BUCKET/FILE

API

Na API, faça uma solicitação para o instances().setMetadata fornecendo os novos metadados e um valor fingerprint.

Uma impressão digital é uma string aleatória de caracteres gerada pelo Compute Engine que é usada para executar o bloqueio otimista. Forneça o valor correspondente da impressão digital para realizar sua solicitação. A impressão digital muda após cada solicitação. Se você fornecer uma impressão digital incompatível, sua solicitação será rejeitada. Dessa forma, só é possível fazer uma atualização por vez, o que evita conflitos.

Para acessar a impressão digital atual de uma instância, execute uma solicitação instances().get:

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance

Em seguida, copie o valor da impressão digital:

{

 ...
 "name": "example-instance",
 "metadata": {
  "kind": "compute#metadata",
  "fingerprint": "zhma6O1w2l8="
 },
 "...
}

Em seguida, faça uma solicitação para o método instances().setMetadata, usando uma das seguintes chaves de metadados e o valor da impressão digital:

startup-script: use essa chave para fornecer diretamente o conteúdo do script de inicialização.
startup-script-url: use essa chave para fornecer um URL do Cloud Storage ao arquivo de script de inicialização.

Exemplo:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance/setMetadata

    {
     "fingerprint": "zhma6O1w2l8=",
     "items": [
      {
       "key": "startup-script-url",
       "value": "gs://BUCKET/FILE"
      }
     ]
    }

Executar um script de inicialização novamente

É possível executar novamente os scripts de inicialização na instância da VM conectando-se à instância e executando um dos seguintes comandos:

Nas imagens Debian, CentOS e RHEL

sudo google_metadata_script_runner startup

GCEMetadataScripts: Starting startup scripts (version YYMMDD.NN).
GCEMetadataScripts: Found startup-script in metadata.
GCEMetadataScripts: startup-script exit status 0
GCEMetadataScripts: Finished running startup scripts.

Nas imagens de SO otimizado para contêineres, Ubuntu e SLES

sudo google_metadata_script_runner --script-type startup --debug

Como visualizar registros de script de inicialização

O resultado do script de inicialização é gravado nos arquivos de registro a seguir:

CentOS e RHEL: /var/log/messages
Debian: /var/log/daemon.log
Ubuntu: /var/log/syslog
SLES: /var/log/messages

Também é possível usar o comando journalctl para ver a saída do script de inicialização.

sudo journalctl -u google-startup-scripts.service

Definir valores personalizados em scripts de inicialização

Quando você executa scripts de inicialização em instâncias, pode haver situações em que se quer usar valores personalizados no script de inicialização. Por exemplo, pode ser útil executar um script de inicialização em instâncias diferentes e fazer com que cada instância gere uma mensagem personalizada.

É possível especificar esses valores personalizados como pares de chave-valor de metadados no momento da criação da instância e fazer referência a eles nos scripts de inicialização. Para mais informações sobre como criar chaves de metadados personalizadas, consulte Como configurar metadados personalizados.

Depois de criar um par de chaves de metadados personalizadas, é possível modificar seu script de inicialização para consultar os novos metadados. Por exemplo, o mesmo script acima pode ser modificado da seguinte maneira:

#! /bin/bash
VALUE_OF_FOO=$(curl http://metadata.google.internal/computeMetadata/v1/instance/attributes/foo -H "Metadata-Flavor: Google")
apt update
apt -y install apache2
cat <<EOF > /var/www/html/index.html
<html><body><h1>Hello World</h1>
<p>The value of foo: $VALUE_OF_FOO</p>
</body></html>
EOF

A seguir

Adicione um script de desligamento.
Use o console serial interativo para resolver problemas de instâncias.
Resolver problemas com scripts de inicialização.

Faça um teste

Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho do Compute Engine em situações reais. Clientes novos também ganham US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

Faça uma avaliação gratuita do Compute Engine