feat(eks): ability to query runtime information from the cluster

packages/@aws-cdk/aws-eks/README.md

@@ -60,10 +60,10 @@ ClusterConfigCommand43AAE40F = aws eks update-kubeconfig --name cluster-xxxxx --
 ```
 
 > The IAM role specified in this command is called the "**masters role**". This is
-> an IAM role that is associated with the `system:masters` [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) 
+> an IAM role that is associated with the `system:masters` [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
 > group and has super-user access to the cluster.
 >
-> You can specify this role using the `mastersRole` option, or otherwise a role will be 
+> You can specify this role using the `mastersRole` option, or otherwise a role will be
 > automatically created for you. This role can be assumed by anyone in the account with
 > `sts:AssumeRole` permissions for this role.
 
@@ -384,7 +384,7 @@ and will be applied sequentially (the standard behavior in `kubectl`).
 
 ### Patching Kubernetes Resources
 
-The KubernetesPatch construct can be used to update existing kubernetes
+The `KubernetesPatch` construct can be used to update existing kubernetes
 resources. The following example can be used to patch the `hello-kubernetes`
 deployment from the example above with 5 replicas.
 
@@ -397,6 +397,46 @@ new KubernetesPatch(this, 'hello-kub-deployment-label', {
 })
 ```
 
+### Querying Kubernetes Resources
+
+The `KubernetesGet` construct can be used to query for information about kubernetes resources,
+and use that as part of your CDK application.
+
+For example, you can fetch the address of a [`LoadBalancer`](https://kubernetes.io/docs/concepts/services-networking/service/#loadbalancer) type service:
+
+```typescript
+// query the load balancer address
+const myServiceAddress = new KubernetesGet(this, 'LoadBalancerAttribute', {
+  cluster: cluster,
+  resourceType: 'service',
+  resourceName: 'my-service',
+  jsonPath: '.status.loadBalancer.ingress[0].hostname', // https://kubernetes.io/docs/reference/kubectl/jsonpath/
+});
+
+// pass the address to a lambda function
+const proxyFunction = new lambda.Function(this, 'ProxyFunction', {
+  ...
+  environment: {
+    myServiceAddress: myServiceAddress.value
+  },
+})
+```
+
+#### Service Description
+
+The `ServiceDescription` construct can be used to quickly access information about services. Internally, it uses the `KubernetesGet` resource for all its attributes.
+
+```typescript
+const service = new eks.ServiceDescription(stack, 'MyServiceDescription', {
+  cluster: cluster,
+  serviceName: 'my-service',
+});
+
+const loadBalancerAddress = service.loadBalancerAddress
+```
+
+> You can also fetch the service description from a specific cluster with the `cluster.describeService` method
+
 ### AWS IAM Mapping
 
 As described in the [Amazon EKS User Guide](https://docs.aws.amazon.com/en_us/eks/latest/userguide/add-user-role.html),

packages/@aws-cdk/aws-eks/lib/cluster-resource-provider.ts

@@ -1,8 +1,8 @@
+import * as path from 'path';
 import * as iam from '@aws-cdk/aws-iam';
 import * as lambda from '@aws-cdk/aws-lambda';
 import { Construct, Duration, NestedStack, Stack } from '@aws-cdk/core';
 import * as cr from '@aws-cdk/custom-resources';
-import * as path from 'path';
 
 const HANDLER_DIR = path.join(__dirname, 'cluster-resource-handler');
 const HANDLER_RUNTIME = lambda.Runtime.NODEJS_12_X;

packages/@aws-cdk/aws-eks/lib/cluster.ts

@@ -16,6 +16,7 @@ import { KubernetesResource } from './k8s-resource';
 import { KubectlProvider, KubectlProviderProps } from './kubectl-provider';
 import { Nodegroup, NodegroupOptions  } from './managed-nodegroup';
 import { ServiceAccount, ServiceAccountOptions } from './service-account';
+import { ServiceDescription, DescribeServiceOptions } from './service-description';
 import { LifecycleLabel, renderAmazonLinuxUserData, renderBottlerocketUserData } from './user-data';
 
 // defaults are based on https://eksctl.io
@@ -714,6 +715,18 @@ export class Cluster extends Resource implements ICluster {
     this.defineCoreDnsComputeType(props.coreDnsComputeType ?? CoreDnsComputeType.EC2);
   }
 
+  /**
+   * Describe the service to retrieve runtime information from the cluster.
+   *
+   * @param options The operation options.
+   */
+  public describeService(options: DescribeServiceOptions): ServiceDescription {
+    return new ServiceDescription(this, `Service${options.serviceName}Description`, {
+      cluster: this,
+      ...options,
+    });
+  }
+
   /**
    * Add nodes to this EKS cluster
    *

packages/@aws-cdk/aws-eks/lib/index.ts

@@ -9,4 +9,5 @@ export * from './k8s-patch';
 export * from './k8s-resource';
 export * from './fargate-cluster';
 export * from './service-account';
-export * from './managed-nodegroup';
+export * from './managed-nodegroup';
+export * from './service-description';

packages/@aws-cdk/aws-eks/lib/k8s-get.ts

@@ -0,0 +1,77 @@
+import { Construct, CustomResource, Token, Duration } from '@aws-cdk/core';
+import { Cluster } from './cluster';
+
+/**
+ * Properties for KubernetesGet.
+ */
+export interface KubernetesGetProps {
+  /**
+   * The EKS cluster to fetch attributes from.
+   *
+   * [disable-awslint:ref-via-interface]
+   */
+  readonly cluster: Cluster;
+
+  /**
+   * The resource type to query. (e.g 'service', 'pod'...)
+   */
+  readonly resourceType: string;
+
+  /**
+   * The name of the resource to query.
+   */
+  readonly resourceName: string;
+
+  /**
+   * JSONPath to use in the query.
+   *
+   * @see https://kubernetes.io/docs/reference/kubectl/jsonpath/
+   */
+  readonly jsonPath: string;
+
+  /**
+   * Timeout for waiting on a value.
+   */
+  readonly timeout: Duration;
+
+}
+
+/**
+ * Represents an attribute of a resource deployed in the cluster.
+ * Use this to fetch runtime information about resources.
+ */
+export class KubernetesGet extends Construct {
+  /**
+   * The CloudFormation reosurce type.
+   */
+  public static readonly RESOURCE_TYPE = 'Custom::AWSCDK-EKS-KubernetesGet';
+
+  private _resource: CustomResource;
+
+  constructor(scope: Construct, id: string, props: KubernetesGetProps) {
+    super(scope, id);
+
+    const provider = props.cluster._attachKubectlResourceScope(this);
+
+    this._resource = new CustomResource(this, 'Resource', {
+      resourceType: KubernetesGet.RESOURCE_TYPE,
+      serviceToken: provider.serviceToken,
+      properties: {
+        ClusterName: props.cluster.clusterName,
+        RoleArn: props.cluster._kubectlCreationRole.roleArn,
+        ResourceType: props.resourceType,
+        ResourceName: props.resourceName,
+        JsonPath: props.jsonPath,
+        TimeoutSeconds: props.timeout.toSeconds(),
+      },
+    });
+
+  }
+
+  /**
+   * The value as a string token.
+   */
+  public get value(): string {
+    return Token.asString(this._resource.getAtt('Value'));
+  }
+}

packages/@aws-cdk/aws-eks/lib/kubectl-handler/get/__init__.py

@@ -0,0 +1,76 @@
+import json
+import logging
+import os
+import subprocess
+import time
+
+logger = logging.getLogger()
+logger.setLevel(logging.INFO)
+
+# these are coming from the kubectl layer
+os.environ['PATH'] = '/opt/kubectl:/opt/awscli:' + os.environ['PATH']
+
+outdir = os.environ.get('TEST_OUTDIR', '/tmp')
+kubeconfig = os.path.join(outdir, 'kubeconfig')
+
+def get_handler(event, context):
+    logger.info(json.dumps(event))
+
+    request_type = event['RequestType']
+    props = event['ResourceProperties']
+
+    # resource properties (all required)
+    cluster_name  = props['ClusterName']
+    role_arn      = props['RoleArn']
+
+    # "log in" to the cluster
+    subprocess.check_call([ 'aws', 'eks', 'update-kubeconfig',
+        '--role-arn', role_arn,
+        '--name', cluster_name,
+        '--kubeconfig', kubeconfig
+    ])
+
+    resource_type   = props['ResourceType']
+    resource_name   = props['ResourceName']
+    json_path       = props['JsonPath']
+    timeout_seconds = props['TimeoutSeconds']
+
+    # json path should be surrouded with '{}'
+    path = '{{{0}}}'.format(json_path)
+    if request_type == 'Create' or request_type == 'Update':
+        output = wait_for_output(['get', resource_type, resource_name, "-o=jsonpath='{{{0}}}'".format(json_path)], int(timeout_seconds))
+        return {'Data': {'Value': output}}
+    elif request_type == 'Delete':
+        pass
+    else:
+        raise Exception("invalid request type %s" % request_type)
+
+def wait_for_output(args, timeout_seconds):
+
+  end_time = time.time() + timeout_seconds
+
+  while time.time() < end_time:
+    # the output is surrounded with '', so we unquote
+    output = kubectl(args).decode('utf-8')[1:-1]
+    if output:
+      return output
+    time.sleep(10)
+
+  raise RuntimeError(f'Timeout waiting for output from kubectl command: {args}')
+
+def kubectl(args):
+    retry = 3
+    while retry > 0:
+        try:
+            cmd = [ 'kubectl', '--kubeconfig', kubeconfig ] + args
+            output = subprocess.check_output(cmd, stderr=subprocess.STDOUT)
+        except subprocess.CalledProcessError as exc:
+            output = exc.output
+            if b'i/o timeout' in output and retry > 0:
+                logger.info("kubectl timed out, retries left: %s" % retry)
+                retry = retry - 1
+            else:
+                raise Exception(output)
+        else:
+            logger.info(output)
+            return output

packages/@aws-cdk/aws-eks/lib/kubectl-handler/index.py

@@ -4,6 +4,7 @@
 from apply import apply_handler
 from helm import helm_handler
 from patch import patch_handler
+from get import get_handler
 
 def handler(event, context):
   print(json.dumps(event))
@@ -18,4 +19,7 @@ def handler(event, context):
   if resource_type == 'Custom::AWSCDK-EKS-KubernetesPatch':
     return patch_handler(event, context)
 
+  if resource_type == 'Custom::AWSCDK-EKS-KubernetesGet':
+    return get_handler(event, context)
+
   raise Exception("unknown resource type %s" % resource_type)

packages/@aws-cdk/aws-eks/lib/service-description.ts

@@ -0,0 +1,65 @@
+import { Construct, Duration } from '@aws-cdk/core';
+import { Cluster } from './cluster';
+import { KubernetesGet as KubernetesGet } from './k8s-get';
+
+/**
+ * Options for `cluster.describeService` operation.
+ */
+export interface DescribeServiceOptions {
+  /**
+   * The service name.
+   */
+  readonly serviceName: string;
+
+  /**
+   * Timeout for waiting on service attribute.
+   * For example, the external ip of a load balancer will not immediately available and needs to be waited for.
+   *
+   * @default Duration.minutes(5)
+   */
+  readonly timeout?: Duration;
+
+}
+
+/**
+ * Properties for ServiceDescription.
+ */
+export interface ServiceDescriptionProps extends DescribeServiceOptions {
+
+  /**
+   * The Cluster that the service is deployed in.
+   *
+   * [disable-awslint:ref-via-interface]
+   */
+  readonly cluster: Cluster;
+
+}
+
+/**
+ * Represents the description of an existing kubernetes service.
+ */
+export class ServiceDescription extends Construct {
+
+  /**
+   * Address of the Load Balancer created bu kubernetes in case the service
+   * type is 'LoadBalancer'
+   *
+   * Using this with a non load balancer service will result in an error.
+   * // TODO - Make this undefined in this case instead of throwing.
+   */
+  public readonly loadBalancerAddress: string;
+
+  constructor(scope: Construct, id: string, props: ServiceDescriptionProps) {
+    super(scope, id);
+
+    const loadBalancerAddress = new KubernetesGet(this, 'LoadBalancerAttribute', {
+      cluster: props.cluster,
+      resourceType: 'service',
+      resourceName: props.serviceName,
+      jsonPath: '.status.loadBalancer.ingress[0].hostname',
+      timeout: props.timeout ?? Duration.minutes(5),
+    });
+
+    this.loadBalancerAddress = loadBalancerAddress.value;
+  }
+}