Criar e gerir pastas

As pastas são nós na hierarquia de recursos da Cloud Platform. Uma pasta pode conter projetos, outras pastas ou uma combinação de ambos. Os recursos da organização podem usar pastas para agrupar projetos no nó de recursos da organização numa hierarquia. Por exemplo, o recurso da sua organização pode conter vários departamentos, cada um com o seu próprio conjunto de Trusted Cloud recursos. As pastas permitem-lhe agrupar estes recursos por departamento. As pastas são usadas para agrupar recursos que partilham políticas de permissão ou recusa comuns. Embora uma pasta possa conter várias pastas ou recursos, uma determinada pasta ou recurso pode ter exatamente um elemento principal.

No diagrama seguinte, o recurso de organização "Empresa" tem pastas que representam dois departamentos, "Dept X" e "Dept Y", e uma pasta, "Infraestrutura partilhada", para itens que podem ser comuns a ambos os departamentos. No departamento Y, a empresa tem dois grupos organizados e, nas pastas dos grupos, organiza ainda mais os ficheiros por produtos. A pasta "Produto 1" contém ainda três projetos, cada um com os recursos necessários para o projeto. Isto oferece-lhes um elevado grau de flexibilidade na atribuição de políticas de permissão, recusa ou organização ao nível de detalhe adequado.

Pode usar políticas de permissão e negação ao nível da pasta para controlar o acesso aos recursos que a pasta contém. Por exemplo, se for concedida a função Administrador de instâncias de computação a um utilizador numa pasta, esse utilizador tem a função Administrador de instâncias de computação para todos os projetos na pasta.

Antes de começar

A funcionalidade de pastas só está disponível para clientes do Google Workspace e Cloud ID que tenham um recurso de organização. Para mais informações sobre como adquirir um recurso de organização, consulte o artigo Criar e gerir organizações.

Se estiver a explorar a melhor forma de usar pastas, recomendamos que:

1. Reveja o artigo Controlo de acesso para pastas através do IAM. Este tópico descreve como pode controlar quem tem que tipo de acesso às pastas e aos recursos que contêm.
2. Compreenda como definir autorizações de pastas. As pastas suportam várias funções da IAM diferentes. Se quiser configurar autorizações de forma abrangente para que os utilizadores possam ver a estrutura dos respetivos projetos, atribua as funções Visualizador da organização e Visualizador da pasta ao nível do recurso da organização a todo o domínio. Para restringir a visibilidade a ramos da hierarquia de pastas, atribua a função Leitor de pastas na pasta ou nas pastas que quer que os utilizadores vejam.
3. Crie pastas. Ao planear como organizar os seus recursos da Google Cloud, recomendamos que comece com uma única pasta como uma área de testes onde pode experimentar que hierarquia faz mais sentido para o seu recurso da organização. Pense nas pastas em termos de limites de isolamento entre recursos e pontos de ligação para políticas de acesso e configuração. Pode optar por criar pastas para conter recursos pertencentes a diferentes departamentos e atribuir funções de administrador em pastas para delegar privilégios de administrador. As pastas também podem ser usadas para agrupar recursos pertencentes a aplicações ou a diferentes ambientes, como desenvolvimento, produção ou teste. Use pastas aninhadas para modelar estes diferentes cenários.

Uma situação comum é criar pastas que, por sua vez, contêm pastas ou projetos adicionais, conforme mostrado na imagem acima. Esta estrutura é denominada hierarquia de pastas. Ao criar uma hierarquia de pastas, tenha em atenção o seguinte:

• Pode aninhar pastas até 10 (dez) níveis de profundidade.
• Uma pasta principal não pode conter mais de 300 pastas. Isto refere-se apenas a pastas secundárias diretas. Por sua vez, essas pastas secundárias podem conter pastas ou projetos adicionais.
• Os nomes a apresentar das pastas têm de ser exclusivos no mesmo nível da hierarquia.

Configure autorizações para gerir pastas

Para aceder e gerir pastas, atribui funções de IAM específicas das pastas a grupos específicos de utilizadores. Para saber mais acerca destas funções, consulte o artigo Controlo de acesso para pastas através da IAM. Também recomendamos que reveja as nossas práticas recomendadas para ajudar a identificar a configuração ideal para as autorizações das suas pastas.

Para gerir pastas para o recurso de toda a sua organização, precisa da função de administrador de pastas. Esta função concede ao utilizador autorização para criar, editar, eliminar, mover e alterar autorizações da IAM em pastas, bem como autorização para mover projetos entre pastas.

Inicialmente, apenas o administrador da organização pode atribuir a função de administrador da pasta para o recurso da organização. As contas subsequentes às quais esta função é atribuída podem atribuí-la a outras contas.

Para configurar as autorizações de pastas, siga estes passos:

    gcloud organizations add-iam-policy-binding ORGANIZATION_ID \
    --member=user:USER_ID \
    --role=roles/resourcemanager.folderAdmin

request_json= '{ policy: { version: "1", bindings: [ { role: "roles/folderAdmin",
members: [ "user:admin@myorganization.com", ] }, { role: "roles/folderCreator",
members: [   "user:admin@myorganization.com", ] } , { role: "roles/folderMover",
members: [ "user:admin@myorganization.com", ] } , ] } }'

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer ${bearer_token}" \
-d "$request_json" \
https://cloudresourcemanager.googleapis.com/v3/ORGANIZATION_NAME:setIamPolicy

Criar pastas

Para criar pastas, tem de ter a função de administrador de pastas ou criador de pastas ao nível principal. Por exemplo, para criar pastas ao nível da organização, tem de ter uma destas funções ao nível da organização.

Como parte da criação de uma pasta, tem de lhe atribuir um nome. Os nomes das pastas têm de cumprir os seguintes requisitos:

• O nome pode conter letras, dígitos, espaços, hífenes e sublinhados.
• O nome a apresentar da pasta tem de começar e terminar com uma letra ou um dígito.
• O nome tem de ter entre 3 e 30 carateres.
• O nome tem de ser diferente de todas as outras pastas que partilham a pasta principal.

Para criar uma pasta:

gcloud resource-manager folders create \
   --display-name=[DISPLAY_NAME] \
   --organization=[ORGANIZATION_ID]

gcloud resource-manager folders create \
   --display-name=[DISPLAY_NAME] \
   --folder=[FOLDER_ID]

request_json= '{
  display_name: DISPLAY_NAME,
  parent: ORGANIZATION_NAME
}'

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer ${bearer_token}" \
-d "$request_json" \
https://cloudresourcemanager.googleapis.com/v3/folders

{
  "name": "operations/fc.123456789",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.FolderOperation",
    "displayName": "[DISPLAY_NAME]",
    "operationType": "CREATE"
  }
}

curl -H "Authorization: Bearer ${bearer_token}" \
https://cloudresourcemanager.googleapis.com/v3/operations/fc.123456789

{
  "name": "operations/fc.123456789",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.FolderOperation",
    "displayName": "[DISPLAY_NAME]",
    "operationType": "CREATE"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.Folder",
    "name": "folders/12345",
    "parent": "organizations/123",
    "displayName": "[DISPLAY_NAME]",
    "lifecycleState": "ACTIVE",
    "createTime": "2017-07-19T23:29:26.018Z",
    "updateTime": "2017-07-19T23:29:26.046Z"
  }
}

Adicione etiquetas durante a criação de pastas

As etiquetas oferecem uma forma de criar anotações para recursos. Pode adicionar etiquetas no momento da criação de pastas. Para o fazer, tem de conceder a função Utilizador de etiquetas. Para mais informações sobre as autorizações incluídas nesta função, consulte o artigo Gerir etiquetas em recursos. Só pode adicionar o espaço de nomes para os pares de chave-valor da etiqueta de uma das seguintes formas:

  gcloud resource-manager folders create \
  --display-name=DISPLAY_NAME \
  --organization=ORGANIZATION_ID
  --tags=KEY_VALUE_PAIRS

  POST https://cloudresourcemanager.googleapis.com/v3/projects/
  Authorization: *************
  Content-Type: application/json

  {
    "display_name": "our-folder-456",
    "parent": "organizations/123",
    "tags": {
      "key": "123/environment"
      "value": "production"
    },
"tags": {
      "key": "123/costCenter"
      "value": "marketing"
    }
  }

Configurar o acesso a pastas

Para configurar o acesso a pastas, tem de ter a função de administrador de IAM de pastas ou administrador de pastas ao nível principal.

gcloud resource-manager folders \
  add-iam-policy-binding [FOLDER_ID] \
  --member=user:email1@example.com \
  --role=roles/resourcemanager.folderEditor

gcloud resource-manager folders \
  add-iam-policy-binding [FOLDER_ID] \
  --member=user:email1@example.com \
  --role=roles/resourcemanager.folderViewer

gcloud resource-manager folders \
  set-iam-policy [FOLDER_ID] [POLICY_FILE]

 request_json= '{
   policy: {
     version: "1",
     bindings: [
       {
         role: "roles/resourcemanager.folderEditor",
         members: [
           "user:email1@example.com",
           "user:email2@example.com",
         ]
       }
     ]
   }
 }'

   curl -X POST -H "Content-Type: application/json" \
   -H "Authorization: Bearer ${bearer_token}" \
   -d "$request_json" \
   https://cloudresourcemanager.googleapis.com/v3/[FOLDER_NAME]:setIamPolicy

Criar um projeto numa pasta

Para criar um projeto numa pasta, tem de ter a função de criador de projetos (roles/resourcemanager.projectCreator) na pasta. Esta função pode ser herdada de uma pasta principal.

  gcloud projects create PROJECT_ID --folder FOLDER_ID

   request_json= '{
      name: DISPLAY_NAME, projectId: PROJECT_ID, parent: {id: PARENT_ID, type: PARENT_TYPE}
   }'

   curl -X POST -H "Content-Type: application/json" \
   -H "Authorization: Bearer ${bearer_token}" \
   -d "$request_json" \
   https://cloudresourcemanager.googleapis.com/v3/projects

Não inclua informações confidenciais no nome da pasta nem noutros nomes de recursos. Qualquer referência à pasta ou aos recursos relacionados expõe o nome da pasta e o nome do recurso.

Mover um projeto para uma pasta

Tem de considerar cuidadosamente as implicações das políticas antes de mover um projeto para dentro ou para fora de uma pasta. As políticas que definir ao nível do projeto vão ser movidas com o projeto, mas as políticas herdadas de um recurso principal não vão ser movidas.

Quando move um projeto, todas as políticas de gestão de identidade e de acesso ou políticas da organização que estiverem diretamente anexadas são movidas com ele. No entanto, um projeto na sua hierarquia de recursos também é afetado pelas políticas que herda dos recursos principais. Se um projeto herdar uma função do IAM que conceda aos utilizadores autorização para usar um serviço específico, os utilizadores não terão acesso a esse serviço no destino, a menos que também herdem a autorização no destino.

Por exemplo, considere que uma conta de serviço tem a função Storage Object Creator associada a um utilizador na pasta A. A conta de serviço tem autorizações para carregar dados para o Cloud Storage em qualquer projeto na pasta A. Se moveu um destes projetos para a pasta B, que não tem as mesmas autorizações herdadas, a conta de serviço desse projeto perde a capacidade de carregar dados, o que resulta numa indisponibilidade do serviço.

Estas mesmas considerações aplicam-se se as políticas da organização forem definidas nas pastas de origem e de destino. Tal como as políticas IAM, as políticas organizacionais são herdadas. Desta forma, tem de garantir que as políticas da sua organização são consistentes entre as pastas de origem e de destino.

Para saber mais sobre as políticas de organização, consulte o artigo Introdução ao serviço de políticas de organização.

Para mover um projeto, precisa da função da IAM Project Mover (roles/resourcemanager.projectMover) na pasta de origem e na pasta de destino. Se o recurso não estiver numa pasta, precisa desta função no recurso da organização.

Estas funções concedem-lhe as seguintes autorizações necessárias:

• resourcemanager.projects.update no projeto
• Se o recurso estiver numa pasta: resourcemanager.projects.move na pasta de origem e no destino
• Se o recurso não estiver numa pasta: resourcemanager.projects.move no recurso da organização

Também pode obter estas autorizações com funções personalizadas ou outras funções predefinidas.

gcloud beta projects move PROJECT_ID \
--DESTINATION_TYPE DESTINATION_ID

POST https://cloudresourcemanager.googleapis.com/v3/{name=PROJECT_NAME}:move
{
  "destinationParent": DESTINATION_PARENT
}

Mover uma pasta para outra pasta

Para mover uma pasta para outra pasta, tem de ter a autorização resourcemanager.folders.move para as pastas de origem e de destino.

gcloud resource-manager folders move [FOLDER_ID] \
  --organization=[PARENT_ID]

gcloud resource-manager folders move [FOLDER_ID] \
  --folder=[PARENT_ID]

request_json= '{
   destinationParent: "folders/[DESTINATION_FOLDER_ID]"
}'

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer ${bearer_token} \
-d "$request_json" \
https://cloudresourcemanager.googleapis.com/v3/folders/[DISPLAY_NAME]:move

{
  "name": "operations/fm.1234567890",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.FolderOperation",
    "displayName": "[DISPLAY_NAME]",
    "operationType": "MOVE"
  }
}

curl -H "Authorization: Bearer ${bearer_token}" \
https://cloudresourcemanager.googleapis.com/v3/operations/fm.1234567890

{
  "name": "operations/fm.1234567890",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.FolderOperation",
    "displayName": "[DISPLAY_NAME]",
    "operationType": "MOVE"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.Folder",
    "name": "folders/12345",
    "parent": "folders/98765",
    "displayName": "[DISPLAY_NAME]",
    "lifecycleState": "ACTIVE",
    "createTime": "2017-07-19T23:29:26.018Z",
    "updateTime": "2017-07-20T00:54:44.295Z"
  }
}

Ver ou listar pastas e projetos

Para ver ou listar pastas, tem de ter as funções de Leitor da organização e Leitor de pastas.

Para ver ou listar pastas e projetos:

gcloud resource-manager folders describe FOLDER_ID

gcloud resource-manager folders list \
  --organization ORGANIZATION_ID

gcloud resource-manager folders list \
  --folder FOLDER_ID

gcloud projects list \
  --filter=" parent.id: 'RESOURCE_ID' "

curl -X GET -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${bearer_token}" \
  https://cloudresourcemanager.googleapis.com/v3/[FOLDER_NAME]

curl -X GET -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${bearer_token}" \
  https://cloudresourcemanager.googleapis.com/v3/folders?parent=[PARENT_NAME]

Usar a Google Cloud CLI

Os comandos para interagir com a API Folders com a ferramenta de linha de comandos estão disponíveis no grupo de comandos gcloud resource-manager folders.gcloud

Criar

Para criar uma nova pasta, use gcloud resource-manager folders create com flags que definam o nome da pasta e o ID do recurso da organização ou da pasta na qual quer que seja criada.

gcloud resource-manager folders create \
  --display-name="Super Fantastic Folder" \
  --organization=2518

Created Folder 245321.

Ver

Para ver uma pasta, use gcloud resource-manager folders describe com o ID da pasta que quer ver.

gcloud resource-manager folders describe 245321
name: folders/245321
parent: organizations/2518
display_name: Super Fantastic Folder
lifecycle_state: ACTIVE
create_time: <timestamp info …>
update_time: <timestamp info …>

Lista

Para listar as pastas abaixo de uma pasta, use gcloud resource-manager folders list, transmitindo o ID da pasta na flag --folder. Também pode listar as pastas de nível superior num recurso de organização, usando a flag --organization.

gcloud resource-manager folders list --folder 245321
<table output showing the folders underneath the folder with the specified ID>

gcloud resource-manager folders list --organization 2518
<table output showing folders in this Organization but not in any folder>

Para incluir na lista as pastas para as quais a eliminação é pedida, adicione a flag --show-deleted

gcloud beta resource-manager folders list --folder 245321 --show-deleted
<table output showing all the folders including the delete requested ones underneath the folder with the specified ID>

Pode listar projetos através do comando gcloud projects list, transmitindo o ID do recurso da pasta principal ou da organização na flag --filter.

gcloud projects list --filter=" parent.id: '245321' "
<table output showing the projects underneath the resource with the specified ID>

Para mais informações sobre como as autorizações e os filtros interagem com os comandos de lista, consulte o artigo Listar todos os recursos na sua hierarquia.

Pesquisar

Para pesquisar pastas que correspondam à consulta especificada, use gcloud alpha resource-manager folders search, transmitindo a condição na flag --query. O âmbito da pesquisa são todas as pastas para as quais o utilizador tem autorização de visualização.

gcloud alpha resource-manager folders search --query="name:vij*"
<table output showing the folders with names starting from vij eg. vijeta, vijay-folder>

gcloud alpha resource-manager folders search --query="state:DELETE_REQUESTED"
<table output showing folders for which delete has been requested>

Todas as pastas para as quais o utilizador tem autorização de visualização podem ser apresentadas através do comando gcloud folders search.

gcloud folders search
<table output showing all viewable folders>

Atualizar

As pastas podem ser atualizadas com o comando gcloud resource-manager folders update. Atualmente, só é possível atualizar o campo display_name de uma pasta.

gcloud resource-manager folders update \
  --display-name="Mega Incredible Folder" 245321
name: folders/245321
parent: organizations/2518
display_name: Mega Incredible Folder
lifecycle_state: ACTIVE
create_time: <timestamp info …>
update_time: <recent timestamp info …>

Eliminar

As pastas podem ser eliminadas e restauradas a partir da linha de comandos. Um utilizador tem de ter a função de administrador da pasta ou editor da pasta para ter autorização para eliminar uma pasta. Só pode eliminar uma pasta se estiver vazia.

gcloud resource-manager folders delete 245321
name: folders/245321
parent: organizations/2518
display_name: Mega Incredible Folder
lifecycle_state: DELETE_REQUESTED
create_time: <timestamp info …>
update_time: <recent timestamp info …>

gcloud resource-manager folders undelete 245321
name: folders/245321
parent: organizations/2518
display_name: Mega Incredible Folder
lifecycle_state: ACTIVE
create_time: <timestamp info …>
update_time: <recent timestamp info …>

Project Move

Os projetos podem ser criados em pastas e movidos para pastas através dos comandos gcloud projects create e gcloud projects move existentes. Também pode mover pastas com a opção gcloud resource-manager folders move.

gcloud projects create --folder=245321 fancy-folder-project
project_id: fancy-folder-project
project_number: 905283
parent:
  type: "folder"
  id: 245321
other fields …

gcloud projects move --folder=245321 soon-to-be-fancy-project
project_id: soon-to-be-fancy-project
project_number: 428714
parent:
  type: "folder"
  id: 245321
other fields …

Operações de longa duração

Algumas operações de pastas, como a criação de pastas, podem demorar muito tempo. Para facilitar a realização de várias tarefas em simultâneo, alguns comandos de pastas permitem-lhe executá-los de forma assíncrona. Estes comandos aceitam uma flag --async para ativar o comportamento assíncrono, o que faz com que devolvam imediatamente uma operação de longa duração em vez de esperarem que a operação seja concluída. Pode sondar esta operação com o comando gcloud beta resource-manager operations describe. Atualmente, apenas os comandos folders create e folders move permitem a utilização assíncrona.

gcloud resource-manager folders create \
  --display-name="Awe-Inspiring Async Folder" \
  --organization=2518 \
  --async

name: operations/fc.8572
metadata:
  operation_type: CREATE
  display_name: Awe-Inspiring Async Folder
  destination_parent: organizations/2518
done: false

[wait for some time …]

gcloud beta resource-manager operations describe fc.8572
name: operations/fc.8572
metadata:
  operation_type: CREATE
  display_name: Awe-Inspiring Async Folder
  destination_parent: organizations/2518
done: true
response:
  name: folders/6428
  parent: organizations/2518
  display_name: Awe-Inspiring Async Folder
  lifecycle_state: ACTIVE
  create_time: <recent timestamp info …>
  update_time: <recent timestamp info …>