/v1/api/discoveryConfigs (POST) - BlueCat Edge

Creates a new discovery configuration.

Configuring BAM discovery configurations

POST https://api-<BlueCat.edge.url>/v1/api/discoveryConfigs
Authorization: Bearer authorization token
Content-Type: Application/JSON
{
  "name": "BAM Discovery",
  "pollingInterval": 300,
  "config": {
    "environment": "bam",
    "baseUrl": "http://10.10.10.10",
    "certificate": null,
    "onFailure": "ABANDON",
    "viewConfigs": [
      {
        "configurationName": "BPC",
        "viewName": "Internal",
        "onFailure": "CONTINUE"
      }
    ],
    "username": {
      "type": "vault",
      "field": "vaultUsername"
    },
    "password": {
      "type": "vault",
      "field": "vaultPass"
    }
  },
  "vaultConfig": {
    "baseUrl": "https://vault.com:1234",
    "namespace": "namespace",
    "secretPath": "/secret/path",
    "roleId": "cd913c25-245e-47f4-93e2-c74c9cfd18fc",
    "secretId": "43e9bfb6-0fb3-4d7d-ae40-9a1fb6986f6a"
  },
  "timeout": 1800
}

Body parameters

name—the name of the discovery configuration
pollingInterval—the interval at which the source of the DNS data is polled. The minimum value is 60 seconds.
config—the configuration for the environment that you would like to pull DNS data from. The configuration includes the following:
- environment—the environment where you would like to retrieve the DNS data. For Address Manager discovery configurations, enter the value bam.
- baseUrl—the Address Manager server URL in the following format: <protocol>://<domain>. For example, https://my-bam.com.
- certificate—the Address Manager server certificate or signing certificate. This field is optional if the protocol in the baseURL is http and Address Manager uses a self-signed certificate.
  Note: The file must be in PEM format.
- onFailure—determines how the discovery configuration handles failures to retrieve data. The value can be one of the following:
  - ABANDON—the discovery configuration uses the last successfully retrieved set of DNS data.
  - CONTINUE—the discovery configuration overwrites the DNS data from the last successful retrieval.
- viewConfigs—the information about the DNS view. The configuration includes the following:
  - configurationName—the name of the Address Manager configuration in which the DNS data can be found.
  - viewName—the name of the Address Manager DNS view in which the DNS data can be found.
  - onFailure—determines how the discovery configuration handles failures to retrieve data from this Address Manager configuration and view. The value can be one of the following:
    - ABANDON—the discovery configuration uses the last successfully retrieved set of DNS data.
    - CONTINUE—the discovery configuration overwrites the DNS data from the last successful retrieval.
    Note:
    - The discovery failure options configured per BAM configuration override the discovery option failures configured at the global level.
    - The onFailure field can be omitted from the viewConfigs configuration. If you omit this field, the view configuration uses the discovery option failures configured at the global level.
- username—the API username used to access the DNS data. The API username includes the following information:
  If you are using Edge secrets manager, the enter the following fields:
  - type—the type of API username. If you are using a value stored in Edge secrets manager, enter edge.
  - secretId—the ID of the secret stored in Edge secrets manager.
  If you are using HashiCorp Vault, the enter the following fields:
  - type—the type of API username. If you are using a value stored in HashiCorp Vault, enter vault.
  - field—the ID of the secret stored in Edge secrets manager..
- password—the API password used to access the DNS data. The API username includes the following information:
  If you are using Edge secrets manager, the enter the following fields:
  - type—the type of API password. If you are using a value stored in Edge secrets manager, enter edge.
  - secretId—the ID of the secret stored in Edge secrets manager.
  If you are using HashiCorp Vault, the enter the following fields:
  - type—the type of API password. If you are using a value stored in HashiCorp Vault, enter vault.
  - field—the ID of the secret stored in Edge secrets manager..
vaultConfig—the HashiCorp Vault information.
Note:
- If you are not using HashiCorp Vault to store credentials, you do not need to include this section in the API body.
- HashiCorp Vault is only supported on discovery instances running software version 1.1.0.
The vault configuration includes the following information:
- baseURL—the base URL of HashiCorp Vault server where the secrets are stored, including the port where the server is accessed.
- namespace (required if using HashiCorp Vault namespaces)— If you are using a namespace, the value is the namespace where the user's secrets are stored in the vault. For more information, refer to https://developer.hashicorp.com/vault/docs/enterprise/namespaces.
- secretPath—the path where you have stored the secrets within the HashiCorp Vault server.
  The discovery configuration uses the HashiCorp Vault API to look up secrets. You must prefix paths with /v1/. For example, if secrets are stored within the secret/data/edgeresolver path, the Secret Path value would be /v1/secret/data/edgeresolver.
- roleId—the ID of the secret in Edge secrets manager. This is the ID of the role that you would like to use to authenticate against HashiCorp Vault. For more information, refer to https://developer.hashicorp.com/vault/api-docs/auth/approle#read-approle-role-id.
- secretId—the secret ID generated from the role ID that is used to authenticate against HashiCorp Vault. For more information, refer to https://developer.hashicorp.com/vault/api-docs/auth/approle#generate-new-secret-id.
timeout—the maximum length of time that the Discovery Instance attempts to discover DNS data for the configuration before it times out, in seconds. The default value is 1800 seconds (30 minutes).

Configuring AWS discovery configurations

Attention: AWS discovery configurations can only be associated to discovery instances running software version 1.1.0 and deployed on DNS resolver service running software version 4.0.0.

POST https://api-<BlueCat.edge.url>/v1/api/discoveryConfigs
Authorization: Bearer authorization token
Content-Type: Application/JSON
{
    "name": "AWS Discovery",
    "pollingInterval": 60,
    "config": {
      "environment": "aws",
      "roleArn": "arn:aws:iam::123456789012:role/cloud_resolver_remote",
      "sessionName": "session"
      "externalId": "test",
      "generateReverse": false,
      "regions": ["us-east-1", "us-east-3"],
      "onFailure": "ABANDON",
      "discoverSecondaryOnly": true,
      "accessKeyId": {
        "type": "vault",
        "field": "vaultAccessKeyId"
      },
      "secretAccessKey": {
        "type": "vault",
        "field": "vaultSecretAccessKey"
      },
      "sessionToken": {
        "type": "vault",
        "field": "vaultSessionToken"
      },
      "secondaryConfigs": [
        {
          "roleArn": "role2",
          "sessionName": "session2",
          "externalId": "test-external-2"
        }
      ],
    },
    "vaultConfig": {
      "baseUrl": "https://test-vault.com:1234",
      "namespace": "namespace",
      "secretPath": "/secret/path",
      "roleId": "cd913c25-245e-47f4-93e2-c74c9cfd18fc",
      "secretId": "43e9bfb6-0fb3-4d7d-ae40-9a1fb6986f6a"
    },
    "timeout": 1800
}

Body parameters

name—the name of the discovery configuration
pollingInterval—the interval at which the source of the DNS data is polled. The minimum value is 60 seconds.
config—the configuration for the environment that you would like to pull DNS data from. The configuration includes the following:
- environment—the environment where you would like to retrieve the DNS data. For AWS discovery configurations, enter the value aws.
- roleArn—the Amazon Resource Name (ARN) of the role.
- sessionName—the role session name to assume.
- externalId—the external ID for the role to assume. For more information, refer to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html#id_roles_third-party_external-id.
- generateReverse—indicates whether the discovery configuration automatically generates reverse zones for cloud discovered network spaces.
- regions—the list of AWS regions for which the discovery information retrieves DNS zone information.
- onFailure—determines how the discovery configuration handles failures to retrieve data. The value can be one of the following:
  - ABANDON—the discovery configuration uses the last successfully retrieved set of DNS data.
  - CONTINUE—the discovery configuration overwrites the DNS data from the last successful retrieval.
- discoverSecondaryOnly—indicates whether to only use secondary configurations for discovery. When set to true, you can use secondary accounts to discover resources by assuming roles into them.
- accessKeyId—the AWS access key ID. The access key ID contains the following information:
  If you are using Edge secrets manager, the enter the following fields:
  - type—the type of AWS access key ID. If you are using a value stored in Edge secrets manager, enter edge.
  - secretId—the ID of the secret stored in Edge secrets manager.
  If you are using HashiCorp Vault, the enter the following fields:
  - type—the type of AWS access key ID. If you are using a value stored in HashiCorp Vault, enter vault.
  - field—the ID of the secret stored in Edge secrets manager..
- secretAccessKey—the AWS secret access key. The secret access key contains the following information:
  If you are using Edge secrets manager, the enter the following fields:
  - type—the type of AWS secret access key. If you are using a value stored in Edge secrets manager, enter edge.
  - secretId—the ID of the secret stored in Edge secrets manager.
  If you are using HashiCorp Vault, the enter the following fields:
  - type—the type of AWS secret access key. If you are using a value stored in HashiCorp Vault, enter vault.
  - field—the ID of the secret stored in Edge secrets manager..
- sessionToken—the AWS session token. The session token contains the following information:
  If you are using Edge secrets manager, the enter the following fields:
  - type—the type of AWS session token. If you are using a value stored in Edge secrets manager, enter edge.
  - secretId—the ID of the secret stored in Edge secrets manager.
  If you are using HashiCorp Vault, the enter the following fields:
  - type—the type of AWS session token. If you are using a value stored in HashiCorp Vault, enter vault.
  - field—the ID of the secret stored in Edge secrets manager..
- secondaryConfigs—the secondary AWS configurations to use for discovery. The secondary configurations include the following information:
  - onFailure—determines how the discovery configuration handles failures to retrieve data for the specific secondary configuration. The value can be one of the following:
    - ABANDON—the discovery configuration uses the last successfully retrieved set of DNS data.
    - CONTINUE—the discovery configuration overwrites the DNS data from the last successful retrieval.
    Note: The discovery failure options configured per secondary configuration override the discovery option failures configured at the global level. This field is optional.
  - regions—the list of AWS regions for which the discovery information retrieves DNS zone information for the specific secondary configuration.
  - roleArn—the Amazon Resource Name (ARN) of the role.
  - sessionName—the role session name to assume.
  - externalId—the external ID for the role to assume. For more information, refer to https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html#id_roles_third-party_external-id.
vaultConfig—the HashiCorp Vault information.
Note: If you are not using HashiCorp Vault to store credentials, you do not need to include this section in the API body.
The vault configuration includes the following information:
- baseURL—the base URL of HashiCorp Vault server where the secrets are stored, including the port where the server is accessed.
- namespace (required if using HashiCorp Vault namespaces)— If you are using a namespace, the value is the namespace where the user's secrets are stored in the vault. For more information, refer to https://developer.hashicorp.com/vault/docs/enterprise/namespaces.
- secretPath—the path where you have stored the secrets within the HashiCorp Vault server.
  The discovery configuration uses the HashiCorp Vault API to look up secrets. You must prefix paths with /v1/. For example, if secrets are stored within the secret/data/edgeresolver path, the Secret Path value would be /v1/secret/data/edgeresolver.
- roleId—the ID of the secret in Edge secrets manager. This is the ID of the role that you would like to use to authenticate against HashiCorp Vault. For more information, refer to https://developer.hashicorp.com/vault/api-docs/auth/approle#read-approle-role-id.
- secretId—the secret ID generated from the role ID that is used to authenticate against HashiCorp Vault. For more information, refer to https://developer.hashicorp.com/vault/api-docs/auth/approle#generate-new-secret-id.
timeout—the maximum length of time that the Discovery Instance attempts to discover DNS data for the configuration before it times out, in seconds. The default value is 1800 seconds (30 minutes).

Configuring Azure discovery configurations

Attention: Azure discovery configurations can only be associated to discovery instances running software version 1.1.0 and deployed on DNS resolver service running software version 4.0.0.

POST https://api-<BlueCat.edge.url>/v1/api/discoveryConfigs
Authorization: Bearer authorization token
Content-Type: Application/JSON
{
    "name": "Azure Discovery",
    "pollingInterval": 60,
    "config": {
      "environment": "azure",
      "generateReverse": true,
      "cloudType": "AzureCloud",
      "onFailure": "ABANDON",
      "tenantConfigs": [
        {
          "tenantId": "tenant",
          "cloudType": "AzureCloud",
          "clientId": {
            "type": "vault",
            "secretId": "vaultClientId"
          },
          "clientSecret": {
            "type": "vault",
            "secretId": "vaultClientSecret"
          }
        }
      ]
    },
    "vaultConfig": {
      "baseUrl": "https://vault.com:1234",
      "namespace": "namespace",
      "secretPath": "/secret/path",
      "roleId": "cd913c25-245e-47f4-93e2-c74c9cfd18fc",
      "secretId": "43e9bfb6-0fb3-4d7d-ae40-9a1fb6986f6a"
  },
  "timeout": 1800
}

Body parameters

name—the name of the discovery configuration
pollingInterval—the interval at which the source of the DNS data is polled. The minimum value is 60 seconds.
config—the configuration for the environment that you would like to pull DNS data from. The configuration includes the following:
- environment—the environment where you would like to retrieve the DNS data. For Azure discovery configurations, enter the value azure.
- generateReverse—indicates whether the discovery configuration automatically generates reverse zones for cloud discovered network spaces.
- cloudType—he type of Azure cloud environment that you would like to discover resources in. The cloud type can be one of the following:
  - AzureCloud—for Azure public, commercial cloud. This is the default value.
  - AzureGovCloud—for Azure US Government Cloud.
  - AzureChinaCloud—for Azure China Cloud.
- onFailure—determines how the discovery configuration handles failures to retrieve data. The value can be one of the following:
  - ABANDON—the discovery configuration uses the last successfully retrieved set of DNS data.
  - CONTINUE—the discovery configuration overwrites the DNS data from the last successful retrieval.
- tenantConfigs—the Azure tenant configurations to discover DNS data from. The tenant configurations include the following information:
  - tenantId—the Azure tenant ID.
  - cloudType—the type of Azure cloud environment that you would like to discover resources in for the specific tenant configuration. The cloud type can be one of the following:
    - AzureCloud—for Azure public, commercial cloud. This is the default value.
    - AzureGovCloud—for Azure US Government Cloud.
    - AzureChinaCloud—for Azure China Cloud.
    Note: The cloud type configurations override the cloud type configured at the global level. This field is optional.
  - onFailure—determines how the discovery configuration handles failures to retrieve data for the specific tenant configuration. The value can be one of the following:
    - ABANDON—the discovery configuration uses the last successfully retrieved set of DNS data.
    - CONTINUE—the discovery configuration overwrites the DNS data from the last successful retrieval.
    Note: The discovery failure options configured per tenant configuration override the discovery option failures configured at the global level. This field is optional.
  - clientId—the Azure Client ID used to access the DNS data. The client ID includes the following information:
    If you are using Edge secrets manager, the enter the following fields:
    - type—the type of client ID. If you are using a value stored in Edge secrets manager, enter edge.
    - secretId—the ID of the secret stored in Edge secrets manager.
    If you are using HashiCorp Vault, the enter the following fields:
    - type—the type of client ID. If you are using a value stored in HashiCorp Vault, enter vault.
    - field—the ID of the secret stored in Edge secrets manager..
  - clientSecret—the Azure client secret used to access the DNS data. The client secret includes the following information:
    If you are using Edge secrets manager, the enter the following fields:
    - type—the type of client secret. If you are using a value stored in Edge secrets manager, enter edge.
    - secretId—the ID of the secret stored in Edge secrets manager.
    If you are using HashiCorp Vault, the enter the following fields:
    - type—the type of client secret. If you are using a value stored in HashiCorp Vault, enter vault.
    - field—the ID of the secret stored in Edge secrets manager..
vaultConfig—the HashiCorp Vault information.
Note: If you are not using HashiCorp Vault to store credentials, you do not need to include this section in the API body.
The vault configuration includes the following information:
- baseURL—the base URL of HashiCorp Vault server where the secrets are stored, including the port where the server is accessed.
- namespace (required if using HashiCorp Vault namespaces)— If you are using a namespace, the value is the namespace where the user's secrets are stored in the vault. For more information, refer to https://developer.hashicorp.com/vault/docs/enterprise/namespaces.
- secretPath—the path where you have stored the secrets within the HashiCorp Vault server.
  The discovery configuration uses the HashiCorp Vault API to look up secrets. You must prefix paths with /v1/. For example, if secrets are stored within the secret/data/edgeresolver path, the Secret Path value would be /v1/secret/data/edgeresolver.
- roleId—the ID of the secret in Edge secrets manager. This is the ID of the role that you would like to use to authenticate against HashiCorp Vault. For more information, refer to https://developer.hashicorp.com/vault/api-docs/auth/approle#read-approle-role-id.
- secretId—the secret ID generated from the role ID that is used to authenticate against HashiCorp Vault. For more information, refer to https://developer.hashicorp.com/vault/api-docs/auth/approle#generate-new-secret-id.
timeout—the maximum length of time that the Discovery Instance attempts to discover DNS data for the configuration before it times out, in seconds. The default value is 1800 seconds (30 minutes).

Configuring GCP discovery configurations

Attention: GCP discovery configurations can only be associated to discovery instances running software version 1.1.0 and deployed on DNS resolver service running software version 4.0.0.

POST https://api-<BlueCat.edge.url>/v1/api/discoveryConfigs
Authorization: Bearer authorization token
Content-Type: Application/JSON
{
    "name": "GCP Discovery",
    "pollingInterval": 60,
    "config": {
      "environment": "gcp",
      "generateReverse": false,
      "onFailure": "ABANDON",
      "accountFile": {
        "type": "edge",
        "secretId": "12345678-7b7e-4ce2-b212-602b1af386f3"
      }
      "projectConfigs": [
        {
          "projectId": "test-projectId",
          "onFailure": "CONTINUE"
        },
        {
          "projectId": "test-project-2"
        }
      ]  
    },
    "timeout": 1800
}

Body parameters

name—the name of the discovery configuration
pollingInterval—the interval at which the source of the DNS data is polled. The minimum value is 60 seconds.
config—the configuration for the environment that you would like to pull DNS data from. The configuration includes the following:
- environment—the environment where you would like to retrieve the DNS data. For GCP discovery configurations, enter the value gcp.
- generateReverse—indicates whether the discovery configuration automatically generates reverse zones for cloud discovered network spaces.
- onFailure—determines how the discovery configuration handles failures to retrieve data. The value can be one of the following:
  - ABANDON—the discovery configuration uses the last successfully retrieved set of DNS data.
  - CONTINUE—the discovery configuration overwrites the DNS data from the last successful retrieval.
- accountFile—the GCP service account credential information. The information contains the following:
  If you are using Edge secrets manager, the enter the following fields:
  - type—the type of service account credentials. If you are using a value stored in Edge secrets manager, enter edge.
  - secretId—the ID of the secret stored in Edge secrets manager.
  If you are using HashiCorp Vault, the enter the following fields:
  - type—the type of service account credentials. If you are using a value stored in HashiCorp Vault, enter vault.
  - field—the ID of the secret stored in Edge secrets manager..
- projectConfigs—the GCP project configurations to discover DNS data from. The project configurations include the following information:
  - projectId—the ID of the GCP Project.
  - onFailure—determines how the discovery configuration handles failures to retrieve data for the specific project configuration. The value can be one of the following:
    - ABANDON—the discovery configuration uses the last successfully retrieved set of DNS data.
    - CONTINUE—the discovery configuration overwrites the DNS data from the last successful retrieval.
    Note: The discovery failure options configured per GCP project configuration override the discovery option failures configured at the global level. This field is optional.
vaultConfig—the HashiCorp Vault information.
Note: If you are not using HashiCorp Vault to store credentials, you do not need to include this section in the API body.
The vault configuration includes the following information:
- baseURL—the base URL of HashiCorp Vault server where the secrets are stored, including the port where the server is accessed.
- namespace (required if using HashiCorp Vault namespaces)— If you are using a namespace, the value is the namespace where the user's secrets are stored in the vault. For more information, refer to https://developer.hashicorp.com/vault/docs/enterprise/namespaces.
- secretPath—the path where you have stored the secrets within the HashiCorp Vault server.
  The discovery configuration uses the HashiCorp Vault API to look up secrets. You must prefix paths with /v1/. For example, if secrets are stored within the secret/data/edgeresolver path, the Secret Path value would be /v1/secret/data/edgeresolver.
- roleId—the ID of the secret in Edge secrets manager. This is the ID of the role that you would like to use to authenticate against HashiCorp Vault. For more information, refer to https://developer.hashicorp.com/vault/api-docs/auth/approle#read-approle-role-id.
- secretId—the secret ID generated from the role ID that is used to authenticate against HashiCorp Vault. For more information, refer to https://developer.hashicorp.com/vault/api-docs/auth/approle#generate-new-secret-id.
timeout—the maximum length of time that the Discovery Instance attempts to discover DNS data for the configuration before it times out, in seconds. The default value is 1800 seconds (30 minutes).

Successful response

201 CREATED

Possible error codes:

BAD REQUEST - Invalid request
INTERNAL SERVER ERROR - Unexpected error

/v1/api/discoveryConfigs (POST) - BlueCat Edge - Service Point v4.x.x

BlueCat Edge User Guide

Configuring BAM discovery configurations

Configuring AWS discovery configurations

Configuring Azure discovery configurations

Configuring GCP discovery configurations