github.com/StackExchange/dnscontrol/v4@v4.11.0/documentation/provider/gcloud.md (about)

     1  ## Configuration
     2  
     3  To use this provider, add an entry to `creds.json` with `TYPE` set to `GCLOUD`.
     4  
     5  For authentication you can either include a Service Account Key in the file or use Application Default Credentials (ADC)
     6  
     7  ### Using a Service Account Key
     8  Copy the full JSON object into your `creds.json`. Newlines in the private key need to be replaced with `\n`.
     9  
    10  Example:
    11  
    12  {% code title="creds.json" %}
    13  ```json
    14  {
    15    "gcloud": {
    16      "TYPE": "GCLOUD",
    17      "type": "service_account",
    18      "project_id": "mydnsproject",
    19      "private_key_id": "0000000000000000000000000000000000000000",
    20      "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvAIBADL00000000000000000OX\nih0DbxhiQ==\n-----END PRIVATE KEY-----\n",
    21      "client_email": "dnscontrolacct@mydnsproject.iam.gserviceaccount.com",
    22      "client_id": "000000000000000000000",
    23      "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    24      "token_uri": "https://accounts.google.com/o/oauth2/token",
    25      "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
    26      "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/dnscontrolsdfsdfsdf%40craigdnstest.iam.gserviceaccount.com",
    27      "name_server_set": "optional_name_server_set_name (contact your TAM)"
    28    }
    29  }
    30  ```
    31  {% endcode %}
    32  
    33  **Note**:
    34  
    35  * Don't confuse the `TYPE` and `type` fields.  `TYPE` is set to `GCLOUD` and specifies which provider type to use.  `type` specifies the type of account in use.
    36  * The JSON object that Google sends includes many, many fields.  The `project_id`, `private_key`, and `client_email`, are the only fields that are required. The example above includes all fields.
    37  * `name_server_set` is optional and requires special permission from your TAM at Google in order to setup (See [Name server sets](#name-server-sets) below)
    38  See [the Activation section](#activation) for some tips on obtaining these credentials.
    39  
    40  ### Using Application Default Credentials
    41  If you prefer to authenticate using ADC you only need to specify `project_id` in your `creds.json` file.
    42  
    43  Example:
    44  
    45  ```json
    46  {
    47    "gcloud": {
    48      "TYPE": "GCLOUD",
    49      "project_id": "mydnsproject"
    50    }
    51  }
    52  ```
    53  
    54  **Note:** To use ADC, make sure to not add any `private_key` value to your configuration as that will prevent DNSControl from attempting to use ADC.
    55  
    56  ## Metadata
    57  This provider does not recognize any special metadata fields unique to google cloud dns.
    58  
    59  ## Usage
    60  An example configuration:
    61  
    62  {% code title="dnsconfig.js" %}
    63  ```javascript
    64  var REG_NAMECOM = NewRegistrar("name.com");
    65  var DSP_GCLOUD = NewDnsProvider("gcloud");
    66  
    67  D("example.com", REG_NAMECOM, DnsProvider(DSP_GCLOUD),
    68      A("test", "1.2.3.4"),
    69  END);
    70  ```
    71  {% endcode %}
    72  
    73  ## Activation
    74  1. Go to your app-engine console and select the appropriate project.
    75  2. Go to "API Manager > Credentials", and create a new "Service Account Key"
    76     ![Create new Service Accoun](../assets/gcloud/create-credentials-service-account-key.png)
    77  3. Choose an existing user, or create a new one. The user requires the "DNS Administrator" role.
    78  4. Download the JSON key and copy it into your `creds.json` under the name of your gcloud provider.
    79  
    80  ## New domains
    81  If a domain does not exist in your Google Cloud DNS account, DNSControl
    82  will *not* automatically add it with the `push` command. You'll need to do that via the
    83  control panel manually or via the `create-domains` command.
    84  
    85  ## Name server sets
    86  
    87  This optional feature lets you pin domains to a set of GCLOUD name servers.  The `nameServerSet` field is exposed in their API but there is
    88  currently no facility for creating a name server set.  You need special permission from your technical account manager at Google and they
    89  will enable it on your account, responding with a list of names to use in the `name_server_set` field above.
    90  
    91  > `name_server_set` only applies on `create-domains` at the moment. Additional work needs to be done to support it during `push`
    92  
    93  ## Private Domains
    94  
    95  This optional feature allows for the instantiation of Google Cloud DNS zones with the `Visibility` field set to `private` and with specific Google Cloud VPC Networks granted visibility to the zone.
    96  
    97  Example:
    98  
    99  {% code title="dnsconfig.js" %}
   100  ```javascript
   101  var REG_NAMECOM = NewRegistrar("name.com");
   102  var DSP_GCLOUD = NewDnsProvider("gcloud", {
   103      "visibility": "private",
   104      "networks": [
   105          "https://www.googleapis.com/compute/v1/projects/mydnsproject/global/networks/myvpcnetwork",
   106          "my2ndvpcnetwork"
   107      ]
   108  });
   109  
   110  D("example.tld", REG_NAMECOM, DnsProvider(DSP_GCLOUD),
   111      A("test", "1.2.3.4"),
   112  END);
   113  ```
   114  {% endcode %}
   115  
   116  > `visiblity` and `networks` only applies on `create-domains` at the moment. Neither setting is enforced by the provider after a zone is created.  Additional work is required to support modifications to `networks` visibility during `push`, however the API will not permit `visibility` to be modified on an existing zone.
   117  
   118  > `networks` may be specified using the network name if the VPC network exists in `project_id`
   119  
   120  > multiple network urls may be specified in `networks`
   121  
   122  > split horizon zones using the `GCLOUD` provider are currently only supported when the providers' credentials target separate `project_id` values
   123  
   124  # Debugging credentials
   125  
   126  You can test your `creds.json` entry with the command: `dnscontrol check-creds foo GCLOUD` where `foo` is the name of key used in `creds.json`.  Error messages you might see:
   127  
   128  * `googleapi: Error 403: Permission denied on resource project REDACTED., forbidden`
   129    * Hint: `project_id` may be invalid.
   130  * `private key should be a PEM or plain PKCS1 or PKCS8; parse error:`
   131    * Hint: `private_key` may be invalid.
   132  * `Response: {"error":"invalid_grant","error_description":"Invalid grant: account not found"}`
   133    * Hint: `client_email` may be invalid.