Skip to main content

Use Cloud Providers API

You can create, read, update, and delete Harness Cloud Providers using the Harness API.

This topic provides information on querying and managing all Cloud Provider types.

Before You Begin

Step 1: Create a Cloud Provider

You create a Cloud Provider using the mutation createCloudProvider.

It has the following syntax:

mutation CreateCloudProviderMutation($cloudProvider: CreateCloudProviderInput!) {  
createCloudProvider(input: $cloudProvider) {
clientMutationId
cloudProvider {
id
name
type
}
}
}

For each type of Cloud Provider you want to add, you use the Query Variables section to add its specific inputs.

The requirements for each Cloud Provider type can be found in their input arguments:

  • awsCloudProvider: AwsCloudProviderInput
  • azureCloudProvider: AzureCloudProviderInput
  • gcpCloudProvider: GcpCloudProviderInput
  • k8sCloudProvider: K8sCloudProviderInput
  • pcfCloudProvider: PcfCloudProviderInput
  • physicalDataCenterCloudProvider: PhysicalDataCenterCloudProviderInput
  • spotInstCloudProvider: SpotInstCloudProviderInput

For example, to add a Google Cloud Platform (GCP) Cloud Provider, you would use something similar to the following:

{  
"cloudProvider": {
"cloudProviderType": "GCP",
"gcpCloudProvider": {
"name": "gcp-api-test",
"serviceAccountKeySecretId":"xxxxxx"
}
}
}

Step 2: Update a Cloud Provider

The syntax for the Query Variables when updating is almost identical to the Query Variables when creating, with the addition of cloudProviderId. You simply need to enter the ID of the Cloud Provider you want to update.

For the required update arguments, see:

  • awsCloudProvider: UpdateAwsCloudProviderInput
  • azureCloudProvider: UpdateAzureCloudProviderInput
  • gcpCloudProvider: UpdateGcpCloudProviderInput
  • k8sCloudProvider: UpdateK8sCloudProviderInput
  • pcfCloudProvider: UpdatePcfCloudProviderInput
  • physicalDataCenterCloudProvider: UpdatePhysicalDataCenterCloudProviderInput
  • spotInstCloudProvider: UpdateSpotInstCloudProviderInput

Query — This is the exact same query for all Cloud Provider types:

mutation UpdateCloudProviderMutation($cloudProvider: UpdateCloudProviderInput!) {  
updateCloudProvider(input: $cloudProvider) {
clientMutationId
cloudProvider {
id
name
type
}
}
}

The Query Variables follow this syntax, with cloudProviderId identifying the Cloud Provider to update:

{  
"cloudProvider": {
"cloudProviderType": "PCF",
"cloudProviderId": "fGPZikQkR2-pycuf4PzlQA",
"pcfCloudProvider": {
"name": "pcf-api-test",
"endpointUrl": "api.run.pivotal.io",
"userName": "john.doe@mycompany.com",
"passwordSecretId":"xxxxxx"
}
}
}

Step 3: Delete a Cloud Provider

Deleting a Cloud Provider requires its ID only.

Query — This is the exact same query for all Cloud Provider types:

mutation DeleteCloudProviderMutation($deleteCloudProvider: DeleteCloudProviderInput!) {  
deleteCloudProvider(input: $deleteCloudProvider) {
clientMutationId
}
}

Query Variables, with cloudProviderId identifying the Cloud Provider to delete:

{  
"deleteCloudProvider": {
"cloudProviderId": "xxxxxxx"
}
}

Output:

{  
"data": {
"deleteCloudProvider": {
"clientMutationId": null
}
}
}

Step 4: Find all Cloud Providers by Type

The first step is usually to get a list of all Harness Cloud Providers by type using cloudProviders().

The results are a list of all the matching Cloud Providers and their IDs and names.

You can then use the ID with cloudProviderById() later in this topic.

Here is an example of the list API with cloudProviders().

{  
cloudProviders(
filters: [{ cloudProviderType:{operator: EQUALS, values: [AWS]}
}]
limit: 10
offset: 0
) {
nodes{
id
name
}
}
}

Output example:

{  
"data": {
"cloudProviders": {
"nodes": [
{
"id": "FOGeZTkeTLyH7Vo2zaPcwg",
"name": "harness-aws-prod",
"createdAt": 1498090708170,
"createdBy": {
"id": "igZG8TuNSoijwZ3ZsmiOOQ"
}
},
{
"id": "62q28QZmRO6vvw2UoWgU5Q",
"name": "harness_awd_nonprod",
"createdAt": 1496431015854,
"createdBy": {
"id": "BNxVi6x-R2SeFAGlxo2HtA"
}
}
]
}
}
}

Now you can use the ID with cloudProviderById() below.

Step 5: Search for Cloud Provider by ID

Using the Cloud Providers ID, you can run cloudProvider(cloudProviderId) or cloudProviderById().

First, let's run cloudProvider(cloudProviderId):

{  
cloudProvider(cloudProviderId: "7VquTr1tQmer76b8rIW_0w") {
id
name
type
}
}

Output example:

{  
"data": {
"cloudProvider": {
"id": "7VquTr1tQmer76b8rIW_0w",
"name": "aws",
"type": "AWS"
}
}
}

Next, let use cloudProviderById():

query cloudProviderById {  
cloudProvider(
cloudProviderId: "jzt2wbM_T-O0gser40V8yg"
){
id
name
type
createdAt
createdBy {
id
}
}
}

Output example:

{  
"data": {
"cloudProvider": {
"id": "jzt2wbM_T-O0gser40V8yg",
"name": "aws",
"type": "AWS",
"createdAt": 1508103092828,
"createdBy": {
"id": "m7akhDYLRG6dGFy4G6FEMw"
}
}
}
}

Step 6: Find Cloud Provider by Name

Using the Cloud Provider's name, run cloudProviderByName:

query cloudProviderByName {  
cloudProviderByName(
name: "aws"
){
id
name
type
createdAt
createdBy {
id
}
}
}

Output example:

{  
"data": {
"cloudProviderByName": {
"id": "jzt2wbM_T-O0gser40V8yg",
"name": "aws",
"type": "AWS",
"createdAt": 1508103092828,
"createdBy": {
"id": "m7akhDYLRG6dGFy4G6FEMw"
}
}
}
}

Examples

In this section are examples of creating and updating the different Harness Cloud Provider types.

Each type has different methods for entering credentials. The examples below simply provide a single credential method.

For all of the available methods and syntax, look up the following in the API Explorer Docs:

  • awsCloudProvider: AwsCloudProviderInput
  • azureCloudProvider: AzureCloudProviderInput
  • gcpCloudProvider: GcpCloudProviderInput
  • k8sCloudProvider: K8sCloudProviderInput
  • pcfCloudProvider: PcfCloudProviderInput
  • physicalDataCenterCloudProvider: PhysicalDataCenterCloudProviderInput
  • spotInstCloudProvider: SpotInstCloudProviderInput

Encrypted Keys Requirements

Most of the Cloud Providers require encrypted text or files, which are created in Harness Secrets Management.

In the API, the serviceAccountKeySecretId argument is used to provide the ID of the Harness Encrypted Text or Files.

You can find this ID using the name of the encrypted text secret:

query{  
secretByName(name:"<secret_name>",secretType:ENCRYPTED_TEXT){
... on EncryptedText{
id
name
secretManagerId
}
}
}

The output will give you the ID you need in id:

{  
"data": {
"secretByName": {
"id": "xxxxxx",
"name": "my-secret",
"secretManagerId": "xxxxx"
}
}
}

See Encrypted Text API, Encrypted Files API, Use Encrypted Text Secrets, and Use Encrypted File Secrets.

GCP

The GCP Cloud Provider uses the gcpCloudProvider: GcpCloudProviderInput API.

Create

Query
mutation CreateCloudProviderMutation($cloudProvider: CreateCloudProviderInput!) {  
createCloudProvider(input: $cloudProvider) {
clientMutationId
cloudProvider {
id
name
type
}
}
}
Query Variables (Using Encrypted Key)
{  
"cloudProvider": {
"cloudProviderType": "GCP",
"gcpCloudProvider": {
"name": "gcp-api-test",
"serviceAccountKeySecretId":"xxxxxx"
}
}
}
Query Variables (Using Inherit From Delegate)

Currently, this feature is behind a Feature Flag. Contact Harness Support to enable the feature. Feature Flags can only be removed for Harness Professional and Essentials editions. Once the feature is released to a general audience, it is available for Trial and Community Editions.

{  
"cloudProvider": {
"cloudProviderType": "GCP",
"gcpCloudProvider": {
"name": "gcp-graphql-api-test1",
"useDelegate": true,
"delegateSelector": "primary",
"skipValidation": true
}
}
}
Output
{  
"data": {
"createCloudProvider": {
"clientMutationId": null,
"cloudProvider": {
"id": "1MxfobsdSMmvogK_NMGrNg",
"name": "gcp-api-test",
"type": "GCP"
}
}
}
}

Update

Query
mutation UpdateCloudProviderMutation($cloudProvider: UpdateCloudProviderInput!) {  
updateCloudProvider(input: $cloudProvider) {
clientMutationId
cloudProvider {
id
name
type
}
}
}
Query Variables (Using Encrypted Key)
{  
"cloudProvider": {
"cloudProviderId": "1MxfobsdSMmvogK_NMGrNg",
"cloudProviderType": "GCP",
"gcpCloudProvider": {
"name": "gcp-api-test",
"serviceAccountKeySecretId":"xxxxx"
}
}
}
Query Variables (Using Inherit From Delegate)

Currently, this feature is behind a Feature Flag. Contact Harness Support to enable the feature. Feature Flags can only be removed for Harness Professional and Essentials editions. Once the feature is released to a general audience, it is available for Trial and Community Editions.

{  
"cloudProvider": {
"cloudProviderId": "d9-31Bl7Tj6oEjBf4ONCZw",
"cloudProviderType": "GCP",
"gcpCloudProvider": {
"name": "gcp-graphql-api-test1",
"useDelegate": true,
"delegateSelector": "cidelegate",
"skipValidation": true
}
}
}
Output
{  
"data": {
"updateCloudProvider": {
"clientMutationId": null,
"cloudProvider": {
"id": "1MxfobsdSMmvogK_NMGrNg",
"name": "gcp-api-test",
"type": "GCP"
}
}
}
}

AWS

The AWS Cloud Provider uses the awsCloudProvider: AwsCloudProviderInput API.

Create

Query
mutation CreateCloudProviderMutation($cloudProvider: CreateCloudProviderInput!) {  
createCloudProvider(input: $cloudProvider) {
clientMutationId
cloudProvider {
id
name
type
}
}
}
Query Variables
{  
"cloudProvider": {
"cloudProviderType": "AWS",
"awsCloudProvider": {
"name": "aws-api-test",
"credentialsType": "MANUAL",
"manualCredentials": {
"accessKey": "xxxxxxx",
"secretKeySecretId": "xxxxxxx"
}
}
}
}

The above example is for manual credentials. You can also use ec2IamCredentials. and other settings. See AwsCloudProviderInput the API Explorer Docs.

Output
{  
"data": {
"createCloudProvider": {
"clientMutationId": null,
"cloudProvider": {
"id": "VxnSK60OS8aLryPyBhV0RQ",
"name": "aws-api-test",
"type": "AWS"
}
}
}
}

Update

Query
mutation UpdateCloudProviderMutation($cloudProvider: UpdateCloudProviderInput!) {  
updateCloudProvider(input: $cloudProvider) {
clientMutationId
cloudProvider {
id
name
type
}
}
}
Query Variables
{  
"cloudProvider": {
"cloudProviderType": "AWS",
"cloudProviderId": "VxnSK60OS8aLryPyBhV0RQ",
"awsCloudProvider": {
"name": "aws-api-test",
"credentialsType": "MANUAL",
"manualCredentials": {
"accessKey": "xxxxxx",
"secretKeySecretId": "xxxxxx"
}
}
}
}
Output
{  
"data": {
"updateCloudProvider": {
"clientMutationId": null,
"cloudProvider": {
"id": "VxnSK60OS8aLryPyBhV0RQ",
"name": "aws-api-test",
"type": "AWS"
}
}
}
}

Azure

The Azure Cloud Provider uses the azureCloudProvider: AzureCloudProviderInput API.

Create

Query
mutation CreateCloudProviderMutation($cloudProvider: CreateCloudProviderInput!) {  
createCloudProvider(input: $cloudProvider) {
clientMutationId
cloudProvider {
id
name
type
}
}
}
Query Variables
{  
"cloudProvider": {
"cloudProviderType": "AZURE",
"azureCloudProvider": {
"name": "azure-api-test",
"clientId": "xxxxx",
"tenantId": "xxxxx",
"keySecretId": "xxxxx"
}
}
}
Output
{  
"data": {
"createCloudProvider": {
"clientMutationId": null,
"cloudProvider": {
"id": "fGPZikQkR2-pycuf4PzlQA",
"name": "azure-api-test",
"type": "AZURE"
}
}
}
}

Update

Query
mutation UpdateCloudProviderMutation($cloudProvider: UpdateCloudProviderInput!) {  
updateCloudProvider(input: $cloudProvider) {
clientMutationId
cloudProvider {
id
name
type
}
}
}
Query Variables
{  
"cloudProvider": {
"cloudProviderType": "AZURE",
"cloudProviderId": "fGPZikQkR2-pycuf4PzlQA",
"azureCloudProvider": {
"name": "azure-api-test",
"clientId": "xxxxx",
"tenantId": "xxxxx",
"keySecretId": "xxxxx"
}
}
}
Output
{  
"data": {
"updateCloudProvider": {
"clientMutationId": null,
"cloudProvider": {
"id": "fGPZikQkR2-pycuf4PzlQA",
"name": "azure-api-test",
"type": "AZURE"
}
}
}
}

Pivotal (PCF)

The PCF Cloud Provider uses the pcfCloudProvider: PcfCloudProviderInput API.

Create

Query
mutation CreateCloudProviderMutation($cloudProvider: CreateCloudProviderInput!) {  
createCloudProvider(input: $cloudProvider) {
clientMutationId
cloudProvider {
id
name
type
}
}
}
Query Variables
{  
"cloudProvider": {
"cloudProviderType": "PCF",
"pcfCloudProvider": {
"name": "pcf-api-test",
"endpointUrl": "api.run.pivotal.io",
"userName": "john.doe@mycompany.com",
"passwordSecretId":"xxxxxx"
}
}
}
Output
{  
"data": {
"updateCloudProvider": {
"clientMutationId": null,
"cloudProvider": {
"id": "fGPZikQkR2-pyucf4PzlQA",
"name": "pcf-api-test",
"type": "PCF"
}
}
}
}

Update

Query
mutation UpdateCloudProviderMutation($cloudProvider: UpdateCloudProviderInput!) {  
updateCloudProvider(input: $cloudProvider) {
clientMutationId
cloudProvider {
id
name
type
}
}
}
Query Variables
{  
"cloudProvider": {
"cloudProviderType": "PCF",
"cloudProviderId": "fGPZikQkR2-pycuf4PzlQA",
"pcfCloudProvider": {
"name": "pcf-api-test",
"endpointUrl": "api.run.pivotal.io",
"userName": "john.doe@mycompany.com",
"passwordSecretId":"xxxxxx"
}
}
}
Output
{  
"data": {
"updateCloudProvider": {
"clientMutationId": null,
"cloudProvider": {
"id": "fGPZikQkR2-pyucf4PzlQA",
"name": "pcf-api-test",
"type": "PCF"
}
}
}
}

Spotinst

The Spotinst Cloud Provider uses the spotInstCloudProvider: SpotInstCloudProviderInput API.

Create

Query
mutation CreateCloudProviderMutation($cloudProvider: CreateCloudProviderInput!) {  
createCloudProvider(input: $cloudProvider) {
clientMutationId
cloudProvider {
id
name
type
}
}
}
Query Variables
{  
"cloudProvider": {
"cloudProviderType": "SPOT_INST",
"spotInstCloudProvider": {
"name": "spotinst-api-test",
"accountId": "xxxxxx",
"tokenSecretId": "xxxxxx"
}
}
}
Output
{  
"data": {
"createCloudProvider": {
"clientMutationId": null,
"cloudProvider": {
"id": "oFrVUcq7RTm7h23JK5FJ1g",
"name": "spotinst-api-test",
"type": "SPOT_INST"
}
}
}
}

Update

Query:
mutation UpdateCloudProviderMutation($cloudProvider: UpdateCloudProviderInput!) {  
updateCloudProvider(input: $cloudProvider) {
clientMutationId
cloudProvider {
id
name
type
}
}
}
Query Variables
{  
"cloudProvider": {
"cloudProviderType": "SPOT_INST",
"cloudProviderId": "oFrVUcq7RTm7h23JK5FJ1g",
"spotInstCloudProvider": {
"name": "spotinst-api-test",
"accountId": "xxxxxx",
"tokenSecretId": "xxxxxx"
}
}
}
Output
{  
"data": {
"updateCloudProvider": {
"clientMutationId": null,
"cloudProvider": {
"id": "oFrVUcq7RTm7h23JK5FJ1g",
"name": "spotinst-api-test",
"type": "SPOT_INST"
}
}
}
}

Kubernetes

The Kubernetes Cloud Provider uses the k8sCloudProvider: K8sCloudProviderInput API

Create

Query
mutation CreateCloudProviderMutation($cloudProvider: CreateCloudProviderInput!) {  
createCloudProvider(input: $cloudProvider) {
clientMutationId
cloudProvider {
id
name
type
}
}
}
Query Variables
{  
"cloudProvider": {
"cloudProviderType": "KUBERNETES_CLUSTER",
"k8sCloudProvider": {
"name": "k8s-api-test",
"skipValidation": true,
"clusterDetailsType": "INHERIT_CLUSTER_DETAILS",
"inheritClusterDetails": {
"delegateName": "harness-dev-delegate"
}
}
}
}

The example above inherits credentials from a Harness Delegate (typically running in the target cluster). For manual cluster credential details, use manualClusterDetails: UpdateManualClusterDetails.

Output
{  
"data": {
"createCloudProvider": {
"clientMutationId": null,
"cloudProvider": {
"id": "OmvkypLgQwCdaTvV4JexIg",
"name": "k8s-api-test",
"type": "KUBERNETES_CLUSTER"
}
}
}
}

Update

Query:
mutation UpdateCloudProviderMutation($cloudProvider: UpdateCloudProviderInput!) {  
updateCloudProvider(input: $cloudProvider) {
clientMutationId
cloudProvider {
id
name
type
}
}
}
Query Variables
{  
"cloudProvider": {
"cloudProviderType": "KUBERNETES_CLUSTER",
"cloudProviderId": "OmvkypLgQwCdaTvV4JexIg",
"k8sCloudProvider": {
"name": "k8s-api-test",
"skipValidation": true,
"clusterDetailsType": "INHERIT_CLUSTER_DETAILS",
"inheritClusterDetails": {
"delegateName": "harness-qa-delegate"
}
}
}
}
Output
{  
"data": {
"updateCloudProvider": {
"clientMutationId": null,
"cloudProvider": {
"id": "OmvkypLgQwCdaTvV4JexIg",
"name": "k8s-api-test",
"type": "KUBERNETES_CLUSTER"
}
}
}
}

Physical Data Center

The Physical Data Center Cloud Provider uses the physicalDataCenterCloudProvider: PhysicalDataCenterCloudProviderInput API.

Create

Mutation
mutation CreateCloudProviderMutation($cloudProvider: CreateCloudProviderInput!) {  
createCloudProvider(input: $cloudProvider) {
clientMutationId
cloudProvider {
id
name
type
}
}
}
Query Variables

Physical Data Center is the only Cloud Provider that uses usageScope:

{  
"cloudProvider": {
"cloudProviderType": "PHYSICAL_DATA_CENTER",
"physicalDataCenterCloudProvider": {
"name": "phys-api-test",
"usageScope": {
"appEnvScopes": {
"application": {
"appId": "kk-J4MUAR2qcaIjZ2HanYg"
},
"environment": {
"envId": null,
"filterType": "NON_PRODUCTION_ENVIRONMENTS"
}
}
}
}
}
}

Note that the appId is used in application. You can use filterType instead, but you cannot use appId and filterType together. If you do, you will receive this error:

Exception while fetching data (/createCloudProvider) : Invalid request: Cannot set both appId and filterType in the app filter

Output
{  
"data": {
"createCloudProvider": {
"clientMutationId": null,
"cloudProvider": {
"id": "Prmk_uaKTXqhSO_ZxtGaDQ",
"name": "phys-api-test",
"type": "PHYSICAL_DATA_CENTER"
}
}
}
}

Update

Query
mutation UpdateCloudProviderMutation($cloudProvider: UpdateCloudProviderInput!) {  
updateCloudProvider(input: $cloudProvider) {
clientMutationId
cloudProvider {
id
name
type
}
}
}
Query Variables
{  
"cloudProvider": {
"cloudProviderType": "PHYSICAL_DATA_CENTER",
"cloudProviderId": "Prmk_uaKTXqhSO_ZxtGaDQ",
"physicalDataCenterCloudProvider": {
"name": "phys-api-test",
"usageScope": {
"appEnvScopes": {
"application": {
"appId": "kk-J4MUAR2qcaIjZ2HanYg"
},
"environment": {
"envId": null,
"filterType": "NON_PRODUCTION_ENVIRONMENTS"
}
}
}
}
}
}
Output
{  
"data": {
"updateCloudProvider": {
"clientMutationId": null,
"cloudProvider": {
"id": "Prmk_uaKTXqhSO_ZxtGaDQ",
"name": "phys-api-test",
"type": "PHYSICAL_DATA_CENTER"
}
}
}
}