Configurazione del provider

Configurare il provider Terraform OCI con l'autenticazione necessaria e le variabili di ambiente facoltative.

Nota

Per esempi di file di configurazione Terraform per la creazione di risorse specifiche, vedere Esempi di provider di Oracle Cloud Infrastructure Terraform.

Autenticazione

Per interagire con i servizi Oracle Cloud Infrastructure (OCI) e le risorse supportate, configurare il provider Terraform OCI con le credenziali di autenticazione per un account OCI.

Il provider Terraform OCI supporta quattro metodi di autenticazione:

Autenticazione della chiave API (impostazione predefinita)
Autorizzazione principal istanza
Autorizzazione principal risorsa
Autenticazione token sicurezza
Autenticazione identità carico di lavoro OKE

Autenticazione chiave API

Per impostazione predefinita, il provider Terraform utilizza l'autenticazione della chiave API, ma è possibile specificarla in modo esplicito impostando l'attributo auth su "APIKey" nella definizione del provider. Le chiamate a OCI tramite l'autenticazione della chiave API richiedono di fornire le credenziali riportate di seguito.

tenancy_ocid: OCID della tenancy. Per recuperare il valore, vedere Where to Get the Tenancy's OCID and User's OCID.
user_ocid: OCID dell'utente che chiama l'API. Per recuperare il valore, vedere Where to Get the Tenancy's OCID and User's OCID.
private_key: il contenuto del file di chiavi private. Obbligatorio se private_key_path non è definito e ha la precedenza su private_key_path se sono definiti entrambi. Per i dettagli su come creare e configurare le chiavi, vedere Come generare una chiave di firma API e Come caricare la chiave pubblica.
private_key_path: il percorso (incluso il nome del file) della chiave privata memorizzata nel computer. Obbligatorio se private_key non è definito. Per i dettagli su come creare e configurare le chiavi, vedere Come generare una chiave di firma API e Come caricare la chiave pubblica.
private_key_password: (facoltativa) passphrase utilizzata per la chiave, se cifrata.
fingerprint: impronta per la coppia di chiavi utilizzata. Per ottenere il valore, vedere Come ottenere l'impronta della chiave.
region: un'area OCI. Vedere Aree e domini di disponibilità.
config_file_profile: il nome del profilo se si desidera utilizzare un profilo personalizzato nel file di configurazione OCI per fornire le credenziali di autenticazione. Per ulteriori informazioni, vedere Utilizzo del file di configurazione dell'SDK e della CLI.

Ad esempio, fornire questi valori come variabili di ambiente o all'interno delle variabili di configurazione Terraform.

Autorizzazione principal istanza

Nota

L'autorizzazione del principal dell'istanza si applica solo alle istanze in esecuzione in Oracle Cloud Infrastructure.

Utilizzare l'autorizzazione principal istanza per rimuovere i requisiti per i seguenti attributi nella definizione del provider:

tenancy_ocid
user_ocid
private_key_path
fingerprint

Quando l'autorizzazione del principal dell'istanza è abilitata, il provider può effettuare chiamate API da un'istanza di computazione senza questi attributi.

Per abilitare l'autorizzazione del principal dell'istanza per i provider Terraform OCI, impostare l'attributo auth su "InstancePrincipal" nella definizione del provider, come mostrato nell'esempio riportato di seguito.

variable "region" {}

provider "oci" {
   auth = "InstancePrincipal"
   region = var.region
}

Per ulteriori informazioni, vedere Chiamata di servizi da un'istanza.

Autorizzazione principal risorsa

L'autorizzazione del principal risorsa, ad esempio l'autorizzazione del principal dell'istanza, consente al provider di effettuare chiamate API senza dover fornire le credenziali all'interno della definizione del provider. L'autorizzazione del principal risorsa viene utilizzata per consentire alle risorse, ad esempio una funzione in esecuzione, di accedere ad altre risorse di Oracle Cloud Infrastructure. Per ulteriori informazioni, vedere Accesso ad altre risorse di Oracle Cloud Infrastructure dall'esecuzione di funzioni.

Per abilitare l'autorizzazione del principal risorsa per i provider Terraform OCI, effettuare le operazioni riportate di seguito.

Creare il gruppo dinamico e i criteri necessari per la funzione in esecuzione per gestire altre risorse OCI. Seguire le istruzioni riportate nella sezione Utilizzo della console in Accesso ad altre risorse di Oracle Cloud Infrastructure dall'esecuzione di funzioni e assicurarsi che il criterio consenta la gestione di altre risorse.
Impostare le variabili di ambiente riportate di seguito.
- OCI_RESOURCE_PRINCIPAL_VERSION, contenente il valore 2.2.
  
  Se il valore è 1, l'override dell'area non è supportato.
- OCI_RESOURCE_PRINCIPAL_RPST, che contiene il contenuto raw del file rpst o il percorso assoluto del file rpst, incluso il nome file.
- OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM, contenente il percorso assoluto del file private.pem (incluso il nome del file).
- OCI_RESOURCE_PRINCIPAL_REGION, che contiene l'identificativo dell'area in cui viene distribuito il provider (ad esempio, us-phoenix-1).
Impostare l'attributo auth su "ResourcePrincipal" nella definizione del provider.

Nota

Il valore per region nel blocco del provider sostituisce il valore dell'area impostato dalla variabile di ambiente OCI_RESOURCE_PRINCIPAL_REGION. Questa modifica, introdotta in Terraform Provider versione 5.0.0, non è compatibile con il downward.

Quando il valore della variabile di ambiente OCI_RESOURCE_PRINCIPAL_VERSION è 1, l'override dell'area non è supportato.

Ad esempio:
```
provider "oci" {
   auth = "ResourcePrincipal"
   region = var.region
}
```

Autenticazione token sicurezza

Eseguire Terraform utilizzando un token generato con l'autenticazione basata su token per l'interfaccia CLI. Per abilitare l'autenticazione del token di sicurezza, aggiornare la definizione del provider come indicato di seguito.

Impostare l'attributo auth su SecurityToken.
Fornire un valore per config_file_profile.
Impostare region.

Ad esempio:

# Configure the Oracle Cloud Infrastructure provider to use Security Token authentication
provider "oci" {
  auth = "SecurityToken"
  config_file_profile = "PROFILE"
  region = var.region
}

Importante

Questo token scade dopo un'ora. Evitare di utilizzare questo metodo di autenticazione quando il provisioning delle risorse richiede più di un'ora. Per ulteriori informazioni, vedere Aggiornamento di un token.

Autenticazione identità carico di lavoro OKE

In Kubernetes, un carico di lavoro è un'applicazione in esecuzione su un cluster Kubernetes. Un carico di lavoro può essere un componente dell'applicazione in esecuzione all'interno di un singolo pod o più componenti dell'applicazione in esecuzione all'interno di un set di pod che funzionano insieme. Tutti i pod nel carico di lavoro vengono eseguiti nello stesso spazio di nomi.

In Oracle Cloud Infrastructure, un carico di lavoro in esecuzione su un cluster Kubernetes gestito da Kubernetes Engine (noto anche come OKE) è considerato una risorsa a pieno titolo. Una risorsa di carico di lavoro è identificata dalla combinazione univoca di cluster Kubernetes, spazio di nomi e account di servizio. Questa combinazione univoca viene definita identità del carico di lavoro.

L'autenticazione delle identità del carico di lavoro OKE consente ai carichi di lavoro in esecuzione sui cluster Kubernetes gestiti da Kubernetes Engine di accedere ad altre risorse di Oracle Cloud Infrastructure. Per ulteriori informazioni, vedere Concessione dell'accesso dei carichi di lavoro alle risorse OCI.

Per abilitare l'autenticazione delle identità del carico di lavoro OKE per i provider Terraform OCI, impostare l'attributo auth su "OKEWorkloadIdentity" nella definizione del provider, come mostrato nell'esempio riportato di seguito.

variable "region" {}
provider "oci" {
   auth = "OKEWorkloadIdentity"
   region = var.region
}

Variabili di ambiente

Sono disponibili le seguenti variabili di ambiente per la configurazione del provider.

OCI_DEFAULT_CERTS_PATH (percorso del certificato)

Nota

Utilizzare una sola variabile del percorso del certificato alla volta.
OCI_SDK_APPEND_USER_AGENT (user agent personalizzato)
realm_specific_service_endpoint_template_enabled (endpoint dedicato per accedere in modo sicuro ai bucket di storage)
TF_APPEND_USER_AGENT (user agent personalizzato)
TF_VAR_compartment_ocid (valore di autenticazione OCID del compartimento)
TF_VAR_fingerprint (valore di autenticazione dell'impronta digitale della chiave)
TF_VAR_private_key_path (valore di autenticazione del percorso della chiave privata)
TF_VAR_region (valore area)

Esempio: us-ashburn-1
TF_VAR_tenancy_ocid (valore di autenticazione OCID tenancy)
TF_VAR_user_ocid (valore di autenticazione OCID utente)
USER_AGENT_PROVIDER_NAME (user agent personalizzato)

Variabili di ambiente di esportazione e sourcing

È possibile esportare i valori di autenticazione obbligatori come variabili di ambiente oppure eseguirne l'origine in profili bash diversi durante l'esecuzione dei comandi Terraform.

Se lavori principalmente in un singolo compartimento, valuta l'opportunità di esportare l'OCID del compartimento come variabile di ambiente. L'OCID tenancy è anche l'OCID del compartimento radice e può essere utilizzato dove è richiesto qualsiasi OCID compartimento.

Suggerimento

È possibile rimuovere i blocchi del provider del file di configurazione Terraform se tutti i valori richiesti per l'autenticazione della chiave API vengono forniti come variabili di ambiente o impostati in un file *.tfvars.

Esempio di esportazione di UNIX e Linux

L'esempio di UNIX e Linux bash_profile riportato di seguito si applica quando la configurazione Terraform è limitata a un singolo compartimento o utente.

export OCI_DEFAULT_CERTS_PATH=<certificates_path>
export TF_VAR_tenancy_ocid=<tenancy_OCID>
export TF_VAR_compartment_ocid=<compartment_OCID>
export TF_VAR_user_ocid=<user_OCID>
export TF_VAR_fingerprint=<key_fingerprint>
export TF_VAR_private_key_path=<private_key_path>
export TF_VAR_region=<region>
export USER_AGENT_PROVIDER_NAME=<custom_user_agent>
export OCI_SDK_APPEND_USER_AGENT=<custom_user_agent>
export TF_APPEND_USER_AGENT=<custom_user_agent>

Dopo aver impostato questi valori, aprire un nuovo terminale o creare l'origine delle modifiche al profilo:

$ source ~/.bash_profile

Per ambienti più complessi, considerare la possibilità di gestire più set di variabili di ambiente.

Esempio di esportazione Windows

Nota

Assicurarsi che il formato PEM per le chiavi. Per ulteriori informazioni, vedere Come generare una chiave di firma API.

L'esempio di Windows riportato di seguito si applica quando la configurazione Terraform è limitata a un singolo compartimento o utente.

setx OCI_DEFAULT_CERTS_PATH=<certificates_path>
setx TF_VAR_tenancy_ocid <tenancy_OCID>
setx TF_VAR_compartment_ocid <compartment_OCID>
setx TF_VAR_user_ocid <user_OCID>
setx TF_VAR_fingerprint <key_fingerprint>
setx TF_VAR_private_key_path <private_key_path>
setx TF_VAR_region=<region>
setx USER_AGENT_PROVIDER_NAME=<custom_user_agent>
setx OCI_SDK_APPEND_USER_AGENT=<custom_user_agent>
setx TF_APPEND_USER_AGENT=<custom_user_agent>

Dopo aver impostato questi valori, uscire e riaprire il terminale. Le variabili non sono impostate per la sessione corrente.

Uso degli agenti utente personalizzati

Per utilizzare un User Agent personalizzato, esportare una delle variabili d'ambiente indicate di seguito. Viene presa in considerazione una sola variabile di ambiente alla volta, seguendo questo ordine di priorità:

USER_AGENT_PROVIDER_NAME
OCI_SDK_APPEND_USER_AGENT
TF_APPEND_USER_AGENT

Specifica di un endpoint dedicato per il servizio di storage degli oggetti

Accedi in tutta sicurezza ai bucket di storage nello storage degli oggetti con endpoint dedicati utilizzando il provider Terraform OCI. Quando si configura il provider, utilizzare una variabile di ambiente, un parametro nel blocco del provider o entrambi. Se si utilizzano entrambi, il parametro del blocco del provider ha la precedenza.

La variabile di ambiente è OCI_REALM_SPECIFIC_SERVICE_ENDPOINT_TEMPLATE_ENABLED. Il valore predefinito è false. Impostare il valore su true per utilizzare un endpoint dedicato.

Il parametro del blocco del provider è realm_specific_service_endpoint_template_enabled. Il valore predefinito è false. Impostare il valore su true per utilizzare un endpoint dedicato.

Utilizzo di un solo endpoint dedicato

Nel blocco provider, impostare realm_specific_service_endpoint_template_enabled su true.
```
provider "oci" {
  realm_specific_service_endpoint_template_enabled = true
}
```

Utilizzo degli endpoint predefiniti e dedicati

Utilizzare il meta-argomento dell'alias Terraform per accedere sia agli endpoint di servizio predefiniti che agli endpoint specifici del realm. Sostituire gli endpoint predefiniti con endpoint specifici del realm specificando il parametro del provider nella creazione delle risorse.

Definire un blocco provider per ogni endpoint.

provider "oci" {
  realm_specific_service_endpoint_template_enabled = true
}

provider "oci" {
    #By default realm_specific_service_endpoint_template_enabled = false
}

Utilizzare il metaargomento alias Terraform nel blocco provider per un endpoint dedicato.

Ad esempio, aggiungere alias = "custom_endpoint".

provider "oci" {
  alias = "custom_endpoint"
  realm_specific_service_endpoint_template_enabled = true
}

provider "oci" {
    #By default realm_specific_service_endpoint_template_enabled = false
}

In ogni blocco resource che si desidera utilizzare un endpoint dedicato, fare riferimento al valore provider in base al valore alias.

Ad esempio, aggiungere provider = "custom_endpoint".

L'esempio seguente mostra due blocchi di provider e due blocchi di risorse. In questo esempio, bucket1 utilizza l'endpoint predefinito mentre bucket2 utilizza l'endpoint dedicato.

provider "oci" {
  alias = "custom_endpoint"
  realm_specific_service_endpoint_template_enabled = true
}

provider "oci" {
    #By default realm_specific_service_endpoint_template_enabled = false
}

resource "oci_objectstorage_bucket" "bucket1" {
  compartment_id = var.compartment_ocid1
  namespace      = var.namspace1
  name           = var.name1
  access_type    = var.access_type1
}

resource "oci_objectstorage_bucket" "bucket2" {
  provider = "oci.custom_endpoint"
  compartment_id = var.compartment_ocid2
  namespace      = var.namspace2
  name           = var.name2
  access_type    = var.access_type2
}

Uso del file di configurazione dell'SDK e dell'interfaccia CLI

Importanti

I nomi dei parametri nel file di configurazione dell'SDK e dell'interfaccia CLI sono leggermente diversi.

È possibile definire i valori del provider richiesti nello stesso file ~/.oci/config utilizzato dagli SDK e dall'interfaccia CLI. Per informazioni dettagliate sull'impostazione di questa configurazione, vedere File di configurazione SDK e CLI.

Per impostare un profilo di configurazione OCI non predefinito come valore di ambiente, utilizzare il comando seguente:

export TF_VAR_config_file_profile=<config_file_profile_name>

È inoltre possibile impostare il profilo di configurazione OCI in un blocco provider. Ad esempio:

provider "oci" {
  tenancy_ocid = var.tenancy_ocid
  config_file_profile= var.config_file_profile
}

Ordine di precedenza

Se i parametri sono impostati in più posizioni, l'ordine di precedenza è il seguente:

Variabile di ambiente
Profilo non predefinito nel file di configurazione OCI, se fornito
Profilo DEFAULT nel file di configurazione OCI

Documentazione dell'infrastruttura Oracle Cloud