Instances API 101

Instances API Exploration

Introduction

With the release of the new APIs, we see our customers leveraging them to gather information about the deployed instances by Harness and porting it over into their own Data Aggregation or Dashboarding tooling. With the instances API we can get the metadata about the instances deployed by Harness and surface it up to the user for consumption

Getting the Instances Data

To start, I would recommend getting familiar with our GraphQL API docs. In the API Explorer, we point the user to specific objects that can query! In this post, we will be focusing on Instances

When configuring the query, think about what instances you are interested in querying. Considerations:

  • How many instances do I want to query?
  • What type of instance do I want to query? (i.e. Kubernetes, ECS, SSH)
  • What pieces of information do I need to obtain from this query? (Do I need everything? or do I want specific pieces of information)
  • Why do I need this information?
  • Why am I querying these instances?
  • What value will this information provide me?

The Query

Use Case: Get K8s Pod Information

I want to get information on the Kubernetes Pods I deployed via Harness and port that information into later shell scripts within Harness or a 3rd Party tool like Grafana.

The sample query:

query {
  instances(limit: 100) {
    nodes {
      ... on K8sPodInstance {
        namespace
        podName
        ip
        service {
          id
          name
          description
          deploymentType
        }
      }
    }
  }
}

In the above query, I want to know where the pods are deployed, their ip, and the podName Harness deployed it as. I aslo include information about the service, so I can capture what service the pod was deployed with. In my example, I have a redis worker, redis master, and a php frontend service that I have deployed.

The sample response:

{
  "data": {
    "instances": {
      "nodes": [
        {
          "namespace": "qa",
          "podName": "redis-master-899c97f95-ck22s",
          "ip": "172.17.1.73",
          "service": {
            "id": "AVkFEpIlTyWSSb5nOorOsA",
            "name": "guestbook",
            "description": "k8s php guestbook service with Redis Worker and Master",
            "deploymentType": "KUBERNETES"
          }
        },
        {
          "namespace": "qa",
          "podName": "redis-worker-57d564ff67-dx4g5",
          "ip": "172.17.1.74",
          "service": {
            "id": "AVkFEpIlTyWSSb5nOorOsA",
            "name": "guestbook",
            "description": "k8s php guestbook service with Redis Worker and Master",
            "deploymentType": "KUBERNETES"
          }
        },
        {
          "namespace": "qa",
          "podName": "guestbook-5b976dcc5f-24p75",
          "ip": "172.17.1.72",
          "service": {
            "id": "AVkFEpIlTyWSSb5nOorOsA",
            "name": "guestbook",
            "description": "k8s php guestbook service with Redis Worker and Master",
            "deploymentType": "KUBERNETES"
          }
        },
        {
          "namespace": "qa",
          "podName": "guestbook-5b976dcc5f-4sj7g",
          "ip": "172.17.2.14",
          "service": {
            "id": "AVkFEpIlTyWSSb5nOorOsA",
            "name": "guestbook",
            "description": "k8s php guestbook service with Redis Worker and Master",
            "deploymentType": "KUBERNETES"
          }
        },
        {
          "namespace": "qa",
          "podName": "redis-worker-57d564ff67-6nqcm",
          "ip": "172.17.0.12",
          "service": {
            "id": "AVkFEpIlTyWSSb5nOorOsA",
            "name": "guestbook",
            "description": "k8s php guestbook service with Redis Worker and Master",
            "deploymentType": "KUBERNETES"
          }
        },
        {
          "namespace": "dev",
          "podName": "redis-master-5479dd8c6-sclmz",
          "ip": "172.17.1.70",
          "service": {
            "id": "AVkFEpIlTyWSSb5nOorOsA",
            "name": "guestbook",
            "description": "k8s php guestbook service with Redis Worker and Master",
            "deploymentType": "KUBERNETES"
          }
        },
        {
          "namespace": "dev",
          "podName": "guestbook-6b754bfb66-4gwfk",
          "ip": "172.17.1.71",
          "service": {
            "id": "AVkFEpIlTyWSSb5nOorOsA",
            "name": "guestbook",
            "description": "k8s php guestbook service with Redis Worker and Master",
            "deploymentType": "KUBERNETES"
          }
        },
        {
          "namespace": "dev",
          "podName": "redis-worker-5c9c694bd8-nbv5j",
          "ip": "172.17.0.11",
          "service": {
            "id": "AVkFEpIlTyWSSb5nOorOsA",
            "name": "guestbook",
            "description": "k8s php guestbook service with Redis Worker and Master",
            "deploymentType": "KUBERNETES"
          }
        },
        {
          "namespace": "dev",
          "podName": "redis-worker-5c9c694bd8-lfsng",
          "ip": "172.17.1.69",
          "service": {
            "id": "AVkFEpIlTyWSSb5nOorOsA",
            "name": "guestbook",
            "description": "k8s php guestbook service with Redis Worker and Master",
            "deploymentType": "KUBERNETES"
          }
        }
      ]
    }
  }
}

Use Case: Get ECS Container Instance Information

Similar to the Kubernetes use case, however, the difference is that our ECS implementation exposes different fields for user to query.

My Sample Query:

query {
  instances( 
    limit: 100
    filters: [{instanceType: ECS_CONTAINER_INSTANCE}]){
    nodes{
      ... on EcsContainerInstance {
    		id
      	taskArn
      	taskDefinitionArn
        serviceName
        clusterName
        version
        environment{
          id
          description
          name
        }
      
    }
    }

  }
}

In the above query, I want the id, taskARN, taskDefinitionARN, the serviceNAme that appears in AWS, the clusterName, and Version. I am also interested in the environment information. I want to know what Harness Environment this service has been deployed in.

The sample result:

{
  "data": {
    "instances": {
      "nodes": [
        {
          "id": "VhPgbLWfS7iIsz3iZgzYZQ",
          "taskArn": "arn:aws:ecs:us-east-1:915632791698:task/c4aef370-9535-454f-8119-dc8252f0969f",
          "taskDefinitionArn": "arn:aws:ecs:us-east-1:915632791698:task-definition/Rohan__fargate__nginx__prod:21",
          "serviceName": "Rohan__fargate__nginx__prod__21",
          "clusterName": "blackbelt-ecs",
          "version": "4",
          "environment": {
            "id": "IToj5lwoSXWlUuZy8UB58w",
            "description": "prod environment",
            "name": "prod"
          }
        },
        {
          "id": "Xn2sBpsSS32tykZ7w-B9xQ",
          "taskArn": "arn:aws:ecs:us-east-1:915632791698:task/136bcfd0-b780-45ed-878c-930ba0ebcd4b",
          "taskDefinitionArn": "arn:aws:ecs:us-east-1:915632791698:task-definition/Rohan__fargate__nginx__qa:21",
          "serviceName": "Rohan__fargate__nginx__qa__21",
          "clusterName": "blackbelt-ecs",
          "version": "3",
          "environment": {
            "id": "Yz9ADTuHQWa7ruAcu0p9lg",
            "description": "",
            "name": "qa"
          }
        },
        {
          "id": "V36fu6eXRganQJ7VfDqZ2A",
          "taskArn": "arn:aws:ecs:us-east-1:915632791698:task/ade06dbf-ed7b-4635-8878-65948c0aaff5",
          "taskDefinitionArn": "arn:aws:ecs:us-east-1:915632791698:task-definition/Rohan__basic__fargate__nginx__dev:22",
          "serviceName": "Rohan__basic__fargate__nginx__dev__22",
          "clusterName": "blackbelt-ecs",
          "version": "3",
          "environment": {
            "id": "e1VoejRERS2NlMLta3K19g",
            "description": "dev environment",
            "name": "dev"
          }
        },
        {
          "id": "BS2sJsvjR--xmWMxf6Whiw",
          "taskArn": "arn:aws:ecs:us-east-1:915632791698:task/21193e83-443f-47bd-a417-2df480044675",
          "taskDefinitionArn": "arn:aws:ecs:us-east-1:915632791698:task-definition/Rohan__fargate__nginx__dev:1",
          "serviceName": "Rohan__fargate__nginx__dev__1",
          "clusterName": "blackbelt-ecs",
          "version": "3",
          "environment": {
            "id": "e1VoejRERS2NlMLta3K19g",
            "description": "dev environment",
            "name": "dev"
          }
        }
      ]
    }
  }
}

Conclusion

Well my fellow canaries, hope this helps you get familiar with the Harness Instance APIs. Please feel free to reach out with any questions on using the API, our community is here to help! If you guys have any cool use cases please do share on the Built on Harness Topic!

For more information on Harness GraphQL APIs please checkout the docs: https://docs.harness.io/article/tm0w6rruqv-harness-api

Cheers :smile:

1 Like