NerdGraph tutorial: Configure cloud integrations

This document provides examples of how to use New Relic NerdGraph to query and modify your cloud integration configuration data, including Amazon Web Services (AWS), Microsoft Azure, and Google Cloud Platform (GCP). Using the NerdGraph GraphiQL explorer, you can also query NRQL data.

These examples for querying cloud integration configuration data use GraphQL queries and mutations:

Queries: requests that are intended to only fetch data
Mutations: requests that create or update data on the server

Requirements

Before querying cloud integration data with NerdGraph, ensure you have:

Followed the instructions to connect cloud integrations with New Relic.
Created an API key.

Access the NerdGraph GraphiQL explorer

To access the NerdGraph GraphiQL explorer:

Go to api.newrelic.com/graphiql.
Add any of the following examples.

Query examples

Queries are requests that are intended to only fetch data (no side effects). Queries in NerdGraph are not static, meaning that you can ask for more or less data depending on your needs. For each query, you can specify exactly what data you want to retrieve, as long as it is supported by the schema.

This query returns a list of all provider accounts available in your infrastructure data. Depending on the provider, additional properties can be requested. For example, for GCP, you can also ask for the serviceAccountId property, which is needed when linking a new GCP project to New Relic.

Anonymous:

{
  actor {
    account(id: <NR_ACCOUNT_ID>) {
      cloud {
        providers {
          id
          name
          slug
          ... on CloudGcpProvider {
            serviceAccountId
          }
        }
      }
    }  
  }
}

Named:

query cloudProviders {
  actor {
    account(id: <NR_ACCOUNT_ID>) {
      cloud {
        providers {
          id
          name
          slug
        }
      }
    }
  }
}

This query returns information about a specific provider account for your AWS integration. The properties id, name, slug are requested, along with a list of integrations available to be monitored.

{
  actor {
    account(id: <NR_ACCOUNT_ID>) {
      cloud {
        provider(slug: "aws") {
          id
          slug
          name
          services {
            id
            slug
            name
          }
        }
      }
    }
  }
}

This query returns information about a specific cloud service integration of a provider. In this example, the integration is the AWS ALB monitoring integration and the provider is AWS. The properties id, name, slug, and isAllowed are requested with the available configuration parameters.

{
  actor {
    account(id: <NR_ACCOUNT_ID>) {
      cloud {
        provider(slug: "aws") {
          service(slug: "alb") {
            id
            name
            slug
            isEnabled
          }
        }
      }
    }
  }
}

This query returns the list of cloud accounts enabled with your New Relic account. (Your cloud account associates your New Relic account and a specific provider account with your integration.) You can enable multiple cloud provider accounts in the same New Relic account, even with the same cloud provider.

{
  actor {
    account(id: <NR_ACCOUNT_ID>) {
      cloud {
        linkedAccounts {
          id
          name    
          createdAt
          provider {
            id
            name      
          }
        }
      }
    }
  }
}

This query returns information about a linked account, including the properties name, providerId, and a list of the cloud integrations enabled for monitoring.

{
  actor {
    account(id: <NR_ACCOUNT_ID>) {
      cloud {
        linkedAccount(id: <LINKED_CLOUD_ACCOUNT_ID>) {
          name
          provider {
            id
            name
          }
          integrations {
            id
            name
            createdAt
            updatedAt
          }
        }
      }
    }
  }
}

This query returns all monitored integrations for all the provider cloud accounts.

{
  actor {
    account(id: <NR_ACCOUNT_ID>) {
      cloud {
        linkedAccounts {
          name
          provider {
            id
            name
          }
          integrations {
            id
            name
            service {
              id
              name        
            }
            createdAt
            updatedAt
          }
        }
      }
    }
  }
}

This query returns information about a specific integration from a specific linked account.

{
  actor {
    account(id: <NR_ACCOUNT_ID>) {
      cloud {
        linkedAccount(id: <LINKED_CLOUD_ACCOUNT_ID>) {
          name
          provider {
            id
            name
          }
          integration(id: <INTEGRATION_ID>) {
            id
            name
            service {
              id
              name        
            }
            createdAt
            updatedAt     
          }
        }
      }
    }
  }
}

Mutation examples

Mutations are requests that are intended to have side effects, such as creating or updating data on the server. Mutations require the keyword mutation and the name of the mutation. NerdGraph mutations are restricted to a subset of all possible mutations.

This mutation allows linking cloud provider accounts to a New Relic account, creating one or more linked accounts. It can link one specific cloud provider account (for example aws) to the New Relic account or multiple cloud provider accounts to one New Relic account.

Required:

The parameter <PROVIDER_ACCOUNT_NAME> is required and cannot be empty. It must be unique in your New Relic account.

Other parameters are specific to the provider (AWS, GCP, and Azure) and are also required. In the following sections, you can see which parameters are required for each provider account. After linking an account the createdAt and updatedAt values are equal.

mutation {
  cloudLinkAccount(
      accounts: {
        accountId: <NR_ACCOUNT_ID>,
        aws: [{
          name: <PROVIDER_ACCOUNT_NAME>,
          <other_params>
        }]
        azure: [{
          name: <PROVIDER_ACCOUNT_NAME>,
          <other_params>
        }]
        gcp: [{
          name: <PROVIDER_ACCOUNT_NAME>,
          <other_params>
        }]
      }
    ) {
      linkedAccounts {
        id
        name
        authLabel
        createdAt
        updatedAt
      }
    }
  }
}

This mutation links an AWS provider account to your New Relic account.

mutation {
  cloudLinkAccount(
      accountId: <NR_ACCOUNT_ID>,
      accounts: {
        aws: [{
          name: <PROVIDER_ACCOUNT_NAME>,
          arn: <AWS_ROLE_ARN>
        }]
      }
    ) {
      linkedAccounts {
        id
        name
        authLabel
        createdAt
        updatedAt
      }
    }
  }
}

This mutation links an AWS account sending data through CloudWatch Metric Streams to your New Relic account.

mutation {
  cloudLinkAccount(
      accountId: <NR_ACCOUNT_ID>,
      accounts: {
        aws: [{
          name: <PROVIDER_ACCOUNT_NAME>,
          arn: <AWS_ROLE_ARN>,
          metricCollectionMode: PUSH
        }]
      }
    ) {
      linkedAccounts {
        id
        name
        authLabel
        createdAt
        updatedAt
      }
    }
  }
}

This mutation links a Microsoft Azure cloud subscription to the New Relic account.

mutation {
  cloudLinkAccount(
    accountId: <NR_ACCOUNT_ID>,
    accounts: {
      azure: [{        
        name: <PROVIDER_ACCOUNT_NAME>, 
        applicationId: <azure_application_id>, 
        clientSecret: <azure_application_key>, 
        tenantId: <azure_tenant_id>, 
        subscriptionId: <azure_subscription_id>
       }]          
    }
  ) {
    linkedAccounts {
      id
      name
      authLabel
      createdAt
      updatedAt
    }
  }
}

This mutation rotates the client secret on an existing Microsoft Azure account.

mutation {
  cloudUpdateAccount(
    accountId: <NR_ACCOUNT_ID>
    accounts: {
      azure: {
        linkedAccountId: <NR_LINKED_ACCOUNT_ID>, 
        clientSecret: <azure_secret_token>
      }
    }
  ) {
    linkedAccounts {
      id
      name
      authLabel
      createdAt
      updatedAt
    }
  }
}

This mutation links a GCP project to the New Relic account.

mutation {
  cloudLinkAccount(
    accountId: <NR_ACCOUNT_ID>,
    accounts: {
      gcp: [{        
        name: <PROVIDER_ACCOUNT_NAME>,
        projectId: <GCP_PROJECT_ID>
       }]
    }
  ) {
    linkedAccounts {
      id
      name
      authLabel
      createdAt
      updatedAt
    }
  }
}

This mutation allows you to rename one or more linked provider accounts. The name parameter is required, cannot be empty, and must be unique within your New Relic account.

mutation {
  cloudRenameAccount(
    accountId: <NR_ACCOUNT_ID>,
    accounts: [
      {        
        id: <linked_cloud_account_id_1>,
        name: <new_provider_account_name>
      },
      {
        id: <linked_cloud_account_id_2>,
        name: <new_provider_account_name>
      }
    ]
  ) {
    linkedAccounts {
      id          
      name
    }
  }
}

This mutation allows you to enable the monitoring of one or more specific cloud integrations in an existing cloud account. With this mutation, New Relic records data for the enabled integration from the provider account. For each provider account you have access to different input parameters, matching each available service.

mutation {
  cloudConfigureIntegration (
    accountId: <NR_ACCOUNT_ID>,
    integrations: {
      <provider_slug> : {
        <integration_slug>: [{            
            linkedAccountId: <LINKED_CLOUD_ACCOUNT_ID>,
            <other_parameters> 
        }]
      }
    }
  ) {
    integrations {
      id
      name
      integration {
        id
        slug
      }
      ... on SqsIntegration {
        awsRegions
      }
    }
  }
}

If you have many provider accounts linked, you can enable the same integration in the many cloud accounts at the same time.

For the output of the operation, you can use GraphQL fragments for integration specific configuration parameters.

mutation {
  cloudConfigureIntegration (
    accountId: <NR_ACCOUNT_ID>,
    integrations: {
      <provider_slug> : {
        <integration_slug> : [
          { linkedAccountId: <linked_cloud_account_id_1>  }, 
          { linkedAccountId: <linked_cloud_account_id_2>  }
        ]
      } 
    }
  ) {
    integrations {
      id
      name
      integration {
        id 
        name
      }
      ... on SqsIntegration {
            awsRegions
      }
    }
  }
}

If you have multiple cloud accounts linked, you can also enable multiple integrations in multiple linked cloud accounts at the same time.

For the output of the operation, you can use GraphQL fragments to ask for integration specific configuration parameters.

mutation {
  cloudConfigureIntegration (
    accountId: <NR_ACCOUNT_ID>,
    integrations: {
      <provider_slug_1>: {
        <integration_slug_1>: [
          { linkedAccountId: <linked_cloud_account_id_1> }
        ]
        <integration_slug_2>: [
          { linkedAccountId: <linked_cloud_account_id_2> }
        ]
      },
      <provider_slug_2>: {
        <integration_slug_3>: [
          { linkedAccountId: <linked_cloud_account_id_3>},
          { linkedAccountId: <linked_cloud_account_id_4>}
        ]
      } 
    }
  ) {
    integrations {
      id
      name
      service {
        id 
        name
      }
      ... on SqsIntegration {
            awsRegions
      }
    }
  }
}

This mutation also allows you to modify one or more cloud integrations and change one or more configuration parameters. Each service will have specific parameters that you can modify.

For parameters of a type list (for example, awsRegion) supply the full list. For the output of the operation, you can use GraphQL fragments to ask for integration specific configuration parameters.

mutation {
  cloudConfigureIntegration (
    accountId: <NR_ACCOUNT_ID>,
    integrations: {
      <provider_slug>: {
        <integration_slug>: [{          
          linkedAccountId: <LINKED_CLOUD_ACCOUNT_ID>,
          metricsPollingInterval: <new_polling_interval>,
          <parameter_1>: <value_1>,
          <parameter_N>: <value_N>,
        }]
      }
    }
  ) {
    integrations {
      id
      name
      service {
        id
        slug
      }
      ... on SqsIntegration {            
        metricsPollingInterval,
        <parameter_1>,
        <parameter_N>
      }
    }
    errors {
      type
      message
    }
  }
}

This mutation allows you to disable an integration and stop data collection for the specific cloud integration.

mutation {
  cloudDisableIntegration (
    accountId: <NR_ACCOUNT_ID>,
    integrations: {
      : {
        : [
          { linkedAccountId: <LINKED_CLOUD_ACCOUNT_ID> }
        ]
      }
    }
  ) {
    disabledIntegrations {
      id
      name
      authLabel
      provider {
        id
      }
    }
    errors {
      type
      message
    }
  }
}

This mutation allows you to unlink cloud provider accounts from New Relic account.

Caution

This action can not be undone. However, you can link the account again, but account history will still be lost.

mutation {
  cloudUnlinkAccount (
    accountId: <NR_ACCOUNT_ID>,
    accounts: {
      { linkedAccountId: <LINKED_CLOUD_ACCOUNT_ID> }
    }
  ) {
    unlinkedAccounts {
      id
      name
    }
    errors {
      type
      message
    }
  }
}

Enable an AWS integration

This example uses an AWS SQS integration and assumes you have connected an AWS account to New Relic.

To enable an AWS integration:

Send a query to fetch data about the account, specifically available providers and already created provider accounts:

{
  actor {
    account(id: <NR_ACCOUNT_ID>) {
      cloud {
        providers {
          id 
          name
          slug
        }     
        linkedAccounts {
          name
          integrations {
            id
            name
          }
        }
      }
    }
  }
}

Link an AWS provider account, if there is not one already linked or if you want to link another AWS account:

Use your New Relic account identifier in the <NR_ACCOUNT_ID> parameter.
Provide a name for the provider account in the <PROVIDER_ACCOUNT_NAME>.

Include the ARN of the AWS role used to fetch data from your AWS account.

mutation {
  cloudLinkAccount(
    accountId: <NR_ACCOUNT_ID>,
    accounts: {
      aws: [{        
        name: <PROVIDER_ACCOUNT_NAME>,
        arn: <AWS_ROLE_ARN> }]
    }
  ) {
    linkedAccounts {
      id
      name
      authLabel
      createdAt
      updatedAt
    }
    errors {
      type
      message
    }
  }
}

Use your New Relic account ID in the <NR_ACCOUNT_ID> parameter and the ID of the provider account in the <LINKED_CLOUD_ACCOUNT_ID> parameter value.

mutation {
  cloudConfigureIntegration (
    accountId: <NR_ACCOUNT_ID>,
    integrations: {
      aws: {
        sqs: [
          { linkedAccountId: <LINKED_CLOUD_ACCOUNT_ID> }
        ]
      }
    } 
  ) {
    integrations {
      id
      name
      service {
        id 
        name
      }
    }
    errors {
      type
      message
    }
  }
}

If you have multiple accounts with the same provider account, you can enable the same integration in multiple provider accounts at the same time. Use your New Relic account ID in the <NR_ACCOUNT_ID> parameter and the ID of the provider accounts in the <LINKED_CLOUD_ACCOUNT_ID_n> parameter value.

mutation {
  cloudConfigureIntegration (
    accountId: <NR_ACCOUNT_ID>,
    integrations: {
      aws: {
        sqs: [
          { linkedAccountId: <LINKED_CLOUD_ACCOUNT_ID_1> }, 
          { linkedAccountId: <LINKED_CLOUD_ACCOUNT_ID_2>, configuration_param_1: value_1, configuration_param_2: value_2 }
        ]
      } 
    }
  }) {
    integrations {
      id
      name
      service {
        id 
        name
      }
    }
    errors {
      type
      message
    }
  }
}

Change polling interval for the AWS integration

This example uses an AWS SQS integration and assumes you have connected an AWS account to New Relic. To change the polling interval of an AWS integration:

To update the polling interval for an AWS SQS integration, use your New Relic account ID in the <NR_ACCOUNT_ID> parameter and the id of the linked provider account in the <LINKED_ACCOUNT_ID> parameter value:

mutation {
  cloudConfigureIntegration( 
    accountId: <NR_ACCOUNT_ID>,
    integrations: {
      aws : {
        sqs: [
          { linkedAccountId: <LINKED_CLOUD_ACCOUNT_ID>, metricsPollingInterval: 300 }
        ]
      }
    }
  ) {
    integrations {
      id
      name            
      service {
        id
        slug
      }
      ... on SqsIntegration {
        metricsPollingInterval
      }
    }
    errors {
      type
      message
    }
  }
}

Disable the AWS integration

This example uses an AWS SQS integration and assumes you have connected an AWS account to New Relic. To disable an AWS integration:

Use your New Relic account identifier in the <NR_ACCOUNT_ID> parameter and the ID of the linked cloud account the <LINKED_ACCOUNT_ID> parameter value.

mutation {
  cloudDisableIntegration (
    accountId: <NR_ACCOUNT_ID>,
    integrations: {
      aws: {
        sqs: [
          { linkedAccountId: <LINKED_CLOUD_ACCOUNT_ID> }
        ]
      }
    }
  ) {
  disabledIntegrations {
    id
      accountId
      name 
    }
    errors {
      type
      message
    }
  }
}

NerdGraph tutorial: Configure cloud integrations

Requirements

Access the NerdGraph GraphiQL explorer

Query examples

Available provider accounts

Specific provider account information

Specific integration data from a specific cloud provider

List of enabled cloud accounts

Specific linked account data

Enabled cloud integrations for all linked accounts

Specific cloud integration data for a specific linked account

Mutation examples

Link an account

Link an AWS account

Link an AWS account using CloudWatch Metric Streams

Link a Microsoft Azure account

Rotate an Azure client secret token on a existing account

Link a Google Cloud Platform (GCP) project

Rename one or more cloud accounts

Enable an integration in a cloud account

Enable an integration in multiple cloud accounts

Enable multiple integrations in multiple cloud accounts

Modify an integration's configuration (regions, polling intervals, etc.)

Disable (remove) an integration

Unlink account

Caution

Enable an AWS integration

Send query to fetch account data

Link AWS provider account

Enable the AWS SQS integration

Enable integration in multiple provider accounts

Change polling interval for the AWS integration

Update the polling interval

Disable the AWS integration

Disable the SQS integration

NerdGraph tutorial: Configure cloud integrations

Requirements.css-21sua1{background:none;border:none;width:0;padding:0;}

Access the NerdGraph GraphiQL explorer

Query examples

Specific provider account information

Specific integration data from a specific cloud provider

List of enabled cloud accounts

Specific linked account data

Enabled cloud integrations for all linked accounts

Specific cloud integration data for a specific linked account

Mutation examples

Link an account

Link an AWS account

Link an AWS account using CloudWatch Metric Streams

Link a Microsoft Azure account

Rotate an Azure client secret token on a existing account

Link a Google Cloud Platform (GCP) project

Rename one or more cloud accounts

Enable an integration in a cloud account

Enable an integration in multiple cloud accounts

Enable multiple integrations in multiple cloud accounts

Modify an integration's configuration (regions, polling intervals, etc.)

Disable (remove) an integration

Unlink account

Enable an AWS integration

Send query to fetch account data

Link AWS provider account

Enable the AWS SQS integration

Enable integration in multiple provider accounts

Change polling interval for the AWS integration

Update the polling interval

Disable the AWS integration

Disable the SQS integration

Requirements