The following guidelines will help you identify potential reference fields and configure them in service mappings.
Config Connector uses the concept of resource references, which lets you specify the value of a resource reference field by referencing other resources.
A reference field is a field whose value comes from another Google Cloud resource. The common cases of such values are:
- Resource ID of another GCP resource
- Relative resource name of another GCP resource
- Self link of another GCP resource
- A service-generated value of another GCP resource
You want to look at the Terraform resource documentation when researching the resource. You can also look at the API documentation if needed.
For example, to learn the fields in PubSubTopic, you should check the fields under the Arguments Reference section in google_pubsub_topic, You might also need to check the REST API doc and the tutorial doc.
After you have a basic understanding of the fields for the target resource, these approaches can help you identify whether the field maps to a Google Cloud resource:
- In the GCP tutorial for the target resource, if another GCP resource is required before creating the target resource, and if the value of a field in the other GCP resource is needed when creating the target resource, then the field is likely a reference field. Make a note of the field name and the other GCP resource name.
- In the TF sample for the target resource, if the value of a field is an
attribute reference of another TF resource, then the field is likely
a reference field. Make a note of the field name and the other TF resource type
name, for example the
key_ring
fields mentioned in the cmek sample for PubSubTopic. - If the field name includes:
name
,id
,link
,email
,service_account
, resource names under the same API of the target resource, or field descriptions includerefer
,GCP
/google
/cloud
resources,url
,uri
, and so on. These keywords indicate it's likely that these fields reference Google Cloud resources. Double-check the Google Cloud tutorial and the Terraform documentation to confirm.
Figure out the referenced GCP resource through reading the field description. Once it's determined, note down the field name and the referenced GCP resource name.
Before you can identify what the resource is based on, you must convert the Google Cloud resource name or Terraform type name into a Config Connector kind name. Create a Github question in this repo for help if you still can't find the Config Connector kind name after following these steps:
-
If you know the TF type name, you can do project-scoped search in your local repository with the TF type name. If you find a hit in a service mapping yaml file (under either the
config/servicemappings/
folder or thescripts/resource-autogen/generated/servicemappings/
), the correspondingkind
field in the same resource config should be the KCC kind. -
If you know the GCP resource name, you can either use the search widget to find the corresponding TF type in Terraform doc with the GCP resource name. Then you can find the KCC kind name by following the first step above. Alternatively, you can use the search widget to find the corresponding KCC kind directly in KCC reference doc.
-
If you can't find a KCC kind with the steps above, it's possible that the referenced resource is not supported in KCC. Create a Github question in this repo to clarify. If you've determined that the KCC kind is not supported in KCC, skip ahead to Configure reference resource in the service mappings.
Determine whether the referenced resource is TF-based(Terraform) or DCL-based(Declarative Client Library)
Based on the KCC kind names of the references that you identified above, follow these steps to identify if the referenced resource is DCL or TF-based:
-
Search for the KCC kind name of the referenced resource on the crds folder.
-
Open the CRD file containing the KCC kind name. Search for
dcl2crd
andtf2crd
labels. There should be only one label for each CRD.-
If the resource has the
cnrm.cloud.google.com/dcl2crd: "true"
label, it's a DCL-based resource. -
If the resource has the
cnrm.cloud.google.com/tf2crd: "true"
label, it's a TF-based resource.
-
Next, you identify the type of the reference field. In most cases,
the reference field is a string field, but could be another type like a list.
Check the TF schema of the target resource in the TF provider to determine the
type of the reference field. The URL of file is in the format of
https://github.com/hashicorp/terraform-provider-google-beta/blob/main/google-beta/services/[servicename]/resource_[tf_type_name_without_google_prefix].go
.
You can find a Type
field for each argument, and two most common types are
schema.TypeString
and schema.TypeList
.
-
If the field is a string, follow Configure reference resource in the service mappings to continue configuring the resource reference.
-
If the field is a list:
- If the field is not required, mark it as an ignored field following this example.
- If the field is required, create a Github question in this repo for further discussion.
-
If the field isn't a string or a list, create a Github question in this repo for further discussion.
Based on the information identified in the above sections, configure the service mapping file by providing values for the required fields. Fields can be found in service mapping types
Here is an example configuration:
- tfField: disk.source_snapshot_encryption_key.kms_key_service_account
key: kmsKeyServiceAccountRef
description: |-
The service account being used for the encryption request for the
given KMS key. If absent, the Compute Engine default service account
is used.
gvk:
kind: IAMServiceAccount
version: v1beta1
group: iam.cnrm.cloud.google.com
targetField: email
-
tfField
: TF field which references a GCP resource. In the above example, it'sdisk.source_snapshot_encryption_key.kms_key_service_account
. Note that it is snake case, and it should be a path if it has parent fields. -
description
: description of the tfField, can be found in the Terraform documentation. If the referenced KCC kind is not supported, prependOnly external field is supported to configure the reference.
and a newline in the description. Here is an example. -
key
: the key of the resource being referenced, the convention is to name it as{tfFieldNameInCamelCase}Ref
. Note here we only need the TF field name, no need to include parent fields. Example name:kmsKeyServiceAccountRef
. -
targetField
: the referenced resource's Terraform field that will be extracted and set as the value of the tfField. In the example above, the value of the TF fielddisk.source_snapshot_encryption_key.kms_key_service_account
(whose corresponding fieldspec.disk.sourceSnapshotEncryptionKey.KmsKeyServiceAccountRef
is a reference field in KCC) should be the value of the TF fieldemail
in the corresponding TF type of theIAMServiceAccount
KCC kind. -
gvk
: Group,Version,Kind of the resource being referenced. Note that an alpha only resource cannot be referenced from a v1beta1 resource. After an alpha resource is promoted to beta, we can reference to the beta version of the resource.To identify alpha resources that should not be referenced by a stable v1beta1 resource:
- Check the CRD of the referenced resource in crds folder.
- Search for the value of
cnrm.cloud.google.com/stability-level
in the CRD, if it isalpha
, then it is an alpha resource; otherwise, it contains a stable v1beta1 version.
-
dclBasedResource
: set totrue
if the referenced resource is a DCL-based resource; Do not need to set this field if it not a DCL-based resource (just like the example).