Create an AML AI instance

To use AML AI, create an instance. The AML AI Instance resource sits at the root of all other AML AI resources. Multiple instances can be created in the same region within a Google Cloud project. Instances adhere to the following:

Each instance is specific to a Google Cloud region, ensuring data residency within the Google Cloud region.
Each instance requires all input and output data to exist in the same Google Cloud region and project.
Each instance requires a single associated customer-managed encryption key (CMEK) which is used to encrypt any data created by AML AI.
An instance's child resources inherit the parent instance's location and encryption settings.
Each instance supports customized access management.

The list of available Google Cloud regions can be found on the AML AI locations page. You can map one (or several) geographies in which you operate to one (or several) available AML AI locations, based on your policies. You need to create at least one AML AI instance per AML AI location that you use.

You can run risk scoring both for commercial and retail customers in one AML AI instance. However, create a separate instance to do either of the following:

Restrict access to different sets of AML data to disparate members within your organization
Use different CMEK keys for different sets of AML data

Steps

To create a Google Cloud project and enable the API, see Set up a project and permissions.

Follow these steps to create a CMEK key and an AML AI instance.

Create an encryption key

To create an encryption key, first create a key ring and then the key itself. For more information, see Create encryption keys with Cloud KMS.

Create a key ring

To create a key ring, use the projects.locations.keyRings.create method.

REST

Before using any of the request data, make the following replacements:

KMS_PROJECT_ID: the Google Cloud project ID for the project containing the key ring
LOCATION: the location of the key ring; use one of the supported regions:
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
KEY_RING_ID: a user-defined identifier for the key ring

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://cloudkms.googleapis.com/v1/projects/KMS_PROJECT_ID/locations/LOCATION/keyRings?key_ring_id=KEY_RING_ID"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://cloudkms.googleapis.com/v1/projects/KMS_PROJECT_ID/locations/LOCATION/keyRings?key_ring_id=KEY_RING_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID",
  "createTime": CREATE_TIME
}

gcloud

Before using any of the command data below, make the following replacements:

LOCATION: the location of the key ring; use one of the supported regions:
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
KEY_RING_ID: a user-defined identifier for the key ring

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud kms keyrings create KEY_RING_ID \
  --location LOCATION

Windows (PowerShell)

gcloud kms keyrings create KEY_RING_ID `
  --location LOCATION

Windows (cmd.exe)

gcloud kms keyrings create KEY_RING_ID ^
  --location LOCATION

You should receive an empty response:

Create a key

To create a key, use the projects.locations.keyRings.cryptoKeys method.

REST

Before using any of the request data, make the following replacements:

KMS_PROJECT_ID: the Google Cloud project ID for the project containing the key ring
LOCATION: the location of the key ring; use one of the supported regions:
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
KEY_RING_ID: the user-defined identifier for the key ring
KEY_ID: a user-defined identifier for the key

Request JSON body:

{
  "purpose": "ENCRYPT_DECRYPT"
}

To send your request, choose one of these options:

curl

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

cat > request.json << 'EOF'
{
  "purpose": "ENCRYPT_DECRYPT"
}
EOF

Then execute the following command to send your REST request:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://cloudkms.googleapis.com/v1/projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys?crypto_key_id=KEY_ID"

PowerShell

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

@'
{
  "purpose": "ENCRYPT_DECRYPT"
}
'@  | Out-File -FilePath request.json -Encoding utf8

Then execute the following command to send your REST request:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://cloudkms.googleapis.com/v1/projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys?crypto_key_id=KEY_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID",
  "primary": {
    "name": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID/cryptoKeyVersions/1",
    "state": "ENABLED",
    "createTime": CREATE_TIME,
    "protectionLevel": "SOFTWARE",
    "algorithm": "GOOGLE_SYMMETRIC_ENCRYPTION",
    "generateTime": GENERATE_TIME
  },
  "purpose": "ENCRYPT_DECRYPT",
  "createTime": CREATE_TIME,
  "versionTemplate": {
    "protectionLevel": "SOFTWARE",
    "algorithm": "GOOGLE_SYMMETRIC_ENCRYPTION"
  },
  "destroyScheduledDuration": "86400s"
}

gcloud

Before using any of the command data below, make the following replacements:

LOCATION: the location of the key ring; use one of the supported regions:
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
KEY_RING_ID: the user-defined identifier for the key ring
KEY_ID: a user-defined identifier for the key

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud kms keys create KEY_ID \
  --keyring KEY_RING_ID \
  --location LOCATION \
  --purpose "encryption"

Windows (PowerShell)

gcloud kms keys create KEY_ID `
  --keyring KEY_RING_ID `
  --location LOCATION `
  --purpose "encryption"

Windows (cmd.exe)

gcloud kms keys create KEY_ID ^
  --keyring KEY_RING_ID ^
  --location LOCATION ^
  --purpose "encryption"

You should receive an empty response:

Create an instance

Create an instance for the specific region where the data should reside. This instance references the encryption key you created. For more information, see Customer-managed encryption keys (CMEK).

To create an instance, use the projects.locations.instances.create method.

(The following information is also available in Create and manage instances.)

Before using any of the request data, make the following replacements:

PROJECT_ID: your Google Cloud project ID listed in the IAM Settings
LOCATION: the location of the key ring and the instance; use one of the supported regions:
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
INSTANCE_ID: a user-defined identifier for the instance
KMS_PROJECT_ID: the Google Cloud project ID for the project containing the key ring
KEY_RING_ID: the user-defined identifier for the key ring
KEY_ID: the user-defined identifier for the key
Note: You can't change to a different CMEK key after the instance has been created.

Request JSON body:

{
  "kmsKey": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID"
}

To send your request, choose one of these options:

curl

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

cat > request.json << 'EOF'
{
  "kmsKey": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID"
}
EOF

Then execute the following command to send your REST request:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances?instance_id=INSTANCE_ID"

PowerShell

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

@'
{
  "kmsKey": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID"
}
'@  | Out-File -FilePath request.json -Encoding utf8

Then execute the following command to send your REST request:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances?instance_id=INSTANCE_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

If successful, the response body contains a long-running operation that contains an ID which can be used to retrieve the ongoing status of the asynchronous operation. Copy the returned OPERATION_ID to use in the next section.

Check for the result

Use the projects.locations.operations.get method to check if the instance has been created. If the response contains "done": false, repeat the command until the response contains "done": true. These operations can take a few minutes to several hours to complete.

Before using any of the request data, make the following replacements:

PROJECT_ID: your Google Cloud project ID listed in the IAM Settings
LOCATION: the location of the instance; use one of the supported regions:
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
OPERATION_ID: the identifier for the operation

To send your request, choose one of these options:

curl

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"

PowerShell

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "endTime": END_TIME,
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.financialservices.v1.Instance",
    "name": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID",
    "createTime": CREATE_TIME,
    "updateTime": UPDATE_TIME,
    "kmsKey": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID",
    "state": "ACTIVE"
  }
}

Grant access to the CMEK key

The API automatically creates a service account in your project. The service account needs access to the CMEK key so it can use the key to encrypt and decrypt the underlying data. Grant access to the key.

For PROJECT_NUMBER, use the project number associated with PROJECT_ID. You can find the project number on the IAM Settings page.

gcloud kms keys add-iam-policy-binding "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID/cryptoKeys/KEY_ID" \
  --keyring "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING_ID" \
  --location "LOCATION" \
  --member "serviceAccount:service-PROJECT_NUMBER@gcp-sa-financialservices.iam.gserviceaccount.com" \
  --role="roles/cloudkms.cryptoKeyEncrypterDecrypter" \
  --project="PROJECT_ID"

Contact support

Every time you create an AML AI instance, reach out to support. Include the following information so the AML AI product team can optimally configure your instance based on your needs:

Project ID
Google Cloud region
Instance ID
Expected number of parties in the Party table in datasets within this instance
Expected number of transactions per year in the Transaction table in datasets within this instance

To request additional quota limits, see Quotas.

AML AI makes multiple types of logs available, including platform logs, audit logs, and data access logs. Learn more about each type of logging: