Trabalhar com recursos existentes

Concluído

Os arquivos Bicep geralmente precisam se referir a recursos que foram criados em outro lugar. Esses recursos podem ser criados manualmente, talvez por um colega usando o portal do Azure. Ou eles podem ser criados em outro arquivo Bicep. Há muitas razões pelas quais você precisa se referir a esses recursos, como:

• Você está adicionando um banco de dados SQL a uma instância do servidor lógico SQL do Azure que alguém já criou.
• Você está definindo configurações de diagnóstico para recursos definidos em outro módulo do Bicep.
• Você precisa acessar com segurança as chaves de uma conta de armazenamento que foi implantada manualmente em sua assinatura.

Bicep fornece a palavra-chave existing para você usar nessas situações.

Observação

Os comandos nesta unidade são mostrados para ilustrar conceitos. Não execute os comandos ainda. Você vai praticar o que você aprende aqui em breve.

Consulte os recursos existentes

Dentro de um arquivo Bicep, você pode definir um recurso que já existe. A declaração é semelhante a uma definição de recurso normal, mas há algumas diferenças importantes. No exemplo a seguir de uma definição de recurso existente, a definição refere-se a uma conta de armazenamento chamada toydesigndocs. A conta de armazenamento está no mesmo grupo de recursos no qual seu modelo Bicep está implantando recursos.

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' existing = {
  name: 'toydesigndocs'
}

Vejamos de perto o que compõe essa definição:

• Como faria com um recurso normal, inclua a palavra-chave resource, um nome simbólico e o tipo de recurso e a versão da API.

  Observação

  Lembre-se, o nome simbólico é usado apenas dentro deste arquivo Bicep. Se você criar esse recurso usando um arquivo Bicep e se referir a ele usando o recurso existing em um arquivo Bicep diferente, os nomes simbólicos não precisarão corresponder.

• A palavra-chave existing indica ao Bicep que essa definição de recurso é uma referência a um recurso já criado e que o Bicep não deve tentar implantá-lo.

• A propriedade name é o nome do recurso do Azure da conta de armazenamento que foi implantada anteriormente.

• Não é necessário especificar o location, skuou properties, porque o modelo não implanta o recurso. Limita-se a fazer referência a um recurso existente. Pense nisso como um recurso marcador de posição.

Consulte os recursos filho

Você também pode fazer referência a um recurso filho existente. Use o mesmo tipo de sintaxe que utilizou quando implantou um subrecurso. O exemplo a seguir mostra como você pode se referir a uma sub-rede existente, que é um recurso filho de uma rede virtual. O exemplo usa um recurso filho aninhado, conforme mostrado aqui:

resource vnet 'Microsoft.Network/virtualNetworks@2024-05-01' existing = {
  name: 'toy-design-vnet'

  resource managementSubnet 'subnets' existing = {
    name: 'management'
  }
}

Observe que ambos o recurso pai e o recurso filho têm a palavra-chave existing aplicada.

Em seguida, você pode fazer referência à sub-rede usando o mesmo operador de :: que usa para outros recursos filho aninhados:

output managementSubnetResourceId string = vnet::managementSubnet.id

Consulte recursos fora do grupo de recursos

Muitas vezes, você precisa se referir a recursos em um grupo de recursos diferente. Por exemplo, se você tiver uma rede virtual em um grupo de recursos centralizado, convém implantar uma máquina virtual nessa rede virtual em seu próprio grupo de recursos. Você pode usar a palavra-chave scope para se referir a recursos existentes em um grupo de recursos diferente. O exemplo a seguir mostra como você pode se referir a uma rede virtual chamada toy-design-vnet dentro do grupo de recursos networking-rg:

resource vnet 'Microsoft.Network/virtualNetworks@2024-05-01' existing = {
  scope: resourceGroup('networking-rg')
  name: 'toy-design-vnet'
}

Observe que o scope usa a palavra-chave resourceGroup() para se referir ao grupo de recursos que contém a rede virtual.

Você pode até mesmo fazer referência a recursos dentro de uma assinatura diferente do Azure, desde que a assinatura esteja dentro do seu locatário do Microsoft Entra. Se sua equipe de rede provisionar a rede virtual em uma assinatura diferente, o modelo poderá se referir a ela, como neste exemplo:

resource vnet 'Microsoft.Network/virtualNetworks@2024-05-01' existing = {
  scope: resourceGroup('A123b4567c-1234-1a2b-2b1a-1234abc12345', 'networking-rg')
  name: 'toy-design-vnet'
}

Observe que o scope usa a palavra-chave resourceGroup() para se referir à ID de assinatura do Azure (A123b4567c-1234-1a2b-2b1a-1234abc12345) e ao nome do grupo de recursos que contém a rede virtual.

Agora que você entende como se referir aos recursos existentes, vamos ver como você pode usar esse recurso em seus modelos.

Adicionar recursos filho e de extensão a um recurso existente

Você pode adicionar um recurso filho a um recurso pai já criado usando uma combinação da palavra-chave existing e da palavra-chave parent. O modelo de exemplo a seguir cria um banco de dados SQL do Azure em um servidor que já existe:

resource server 'Microsoft.Sql/servers@2024-05-01-preview' existing = {
  name: serverName
}

resource database 'Microsoft.Sql/servers/databases@2024-05-01-preview' = {
  parent: server
  name: databaseName
  location: location
  sku: {
    name: 'Standard'
    tier: 'Standard'
  }
}

Se você precisar implantar um recurso de extensão em um recurso existente, poderá usar a palavra-chave scope. Aqui está um modelo que usa a palavra-chave existing e a palavra-chave scope para adicionar um bloqueio de recursos a uma conta de armazenamento que já existe:

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' existing = {
  name: 'toydesigndocs'
}

resource lockResource 'Microsoft.Authorization/locks@2020-05-01' = {
  scope: storageAccount
  name: 'DontDelete'
  properties: {
    level: 'CanNotDelete'
    notes: 'Prevents deletion of the toy design documents storage account.'
  }
}

Consulte as propriedades de um recurso existente

Os recursos geralmente precisam se referir às propriedades de outros recursos. Por exemplo, se você implantar um aplicativo, talvez seja necessário saber as chaves ou informações de conexão de outro recurso. Usando a palavra-chave existing, você obtém acesso às propriedades do recurso ao qual está se referindo.

Dica

É uma prática recomendada procurar chaves de outros recursos dessa maneira em vez de passá-las pelas saídas. Você sempre obterá os dados mais up-toatualizados. Além disso, é importante ressaltar que as saídas não são projetadas para lidar com dados seguros, como chaves.

A maneira como você acessa as informações sobre um recurso depende do tipo de informação que você está recebendo. Se for uma propriedade que não é segura, normalmente usa-se apenas o properties do recurso. O modelo de exemplo a seguir implanta um aplicativo do Azure Functions e usa os detalhes de acesso (chave de instrumentação) para uma instância do Application Insights que já foi criada:

resource applicationInsights 'Microsoft.Insights/components@2020-02-02' existing = {
  name: applicationInsightsName
}

resource functionApp 'Microsoft.Web/sites@2024-04-01' = {
  name: functionAppName
  location: location
  kind: 'functionapp'
  properties: {
    siteConfig: {
      appSettings: [
        // ...
        {
          name: 'APPINSIGHTS_INSTRUMENTATIONKEY'
          value: applicationInsights.properties.InstrumentationKey
        }
      ]
    }
  }
}

Neste exemplo, como a chave de instrumentação não é considerada dados confidenciais, ela está disponível na properties do recurso. Quando precisar acessar dados seguros, como as credenciais a serem usadas para acessar um recurso, use a função listKeys(), conforme mostrado no código a seguir:

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' existing = {
  name: storageAccountName
}

resource functionApp 'Microsoft.Web/sites@2024-04-01' = {
  name: functionAppName
  location: location
  kind: 'functionapp'
  properties: {
    siteConfig: {
      appSettings: [
        // ...
        {
          name: 'StorageAccountKey'
          value: storageAccount.listKeys().keys[0].value
        }
      ]
    }
  }
}

Observe que a função listKeys retorna uma matriz keys. O código Bicep recupera a propriedade value do primeiro item na matriz keys. Cada tipo de recurso tem informações diferentes disponíveis a partir da função listKeys(). A extensão Bicep para Visual Studio Code fornece dicas para ajudá-lo a entender os dados que a função listKeys() de cada recurso retorna. A captura de tela a seguir mostra a saída da função listKeys() para uma conta de armazenamento:

Alguns recursos também suportam outras funções. O IntelliSense do Visual Studio Code lista as funções disponíveis para cada recurso. Na captura de tela a seguir, você pode ver que as contas de armazenamento fornecem funções denominadas listAccountSas() e listServiceSas() além de listKeys():

Importante

A função listKeys() fornece acesso a dados confidenciais sobre o recurso. Isso significa que o usuário ou entidade de serviço que executa a implantação precisa ter o nível apropriado de permissão no recurso. Normalmente, esta é a função incorporada Colaborador ou uma função personalizada que atribui a permissão apropriada.