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

Introduce a `KubernetesResourceAttribute` construct that executes `kubectl get` commands to fetch runtime information on kubernetes resources.

Resolves #8394 

BREAKING CHANGE: `cluster.addResource` was renamed to `cluster.addManifest` and `KubernetesResource` was renamed to `KubernetesManifest`

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: iliapolo

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

@@ -31,7 +31,7 @@ const cluster = new eks.Cluster(this, 'hello-eks', {
 });
 
 // apply a kubernetes manifest to the cluster
-cluster.addResource('mypod', {
+cluster.addManifest('mypod', {
   apiVersion: 'v1',
   kind: 'Pod',
   metadata: { name: 'mypod' },
@@ -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.
 
@@ -214,7 +214,7 @@ const cluster = new eks.FargateCluster(this, 'MyCluster', {
 });
 
  // apply k8s resources on this cluster
-cluster.addResource(...);
+cluster.addManifest(...);
 ```
 
 **NOTE**: Classic Load Balancers and Network Load Balancers are not supported on
@@ -266,7 +266,7 @@ the capacity.
 
 ### Kubernetes Resources
 
-The `KubernetesResource` construct or `cluster.addResource` method can be used
+The `KubernetesManifest` construct or `cluster.addManifest` method can be used
 to apply Kubernetes resource manifests to this cluster.
 
 The following examples will deploy the [paulbouwer/hello-kubernetes](https://github.com/paulbouwer/hello-kubernetes)
@@ -309,13 +309,13 @@ const service = {
 };
 
 // option 1: use a construct
-new KubernetesResource(this, 'hello-kub', {
+new KubernetesManifest(this, 'hello-kub', {
   cluster,
   manifest: [ deployment, service ]
 });
 
-// or, option2: use `addResource`
-cluster.addResource('hello-kub', service, deployment);
+// or, option2: use `addManifest`
+cluster.addManifest('hello-kub', service, deployment);
 ```
 
 ##### Kubectl Environment
@@ -342,7 +342,7 @@ import * as request from 'sync-request';
 
 const manifestUrl = 'https://url/of/manifest.yaml';
 const manifest = yaml.safeLoadAll(request('GET', manifestUrl).getBody());
-cluster.addResource('my-resource', ...manifest);
+cluster.addManifest('my-resource', ...manifest);
 ```
 
 Since Kubernetes resources are implemented as CloudFormation resources in the
@@ -356,17 +356,17 @@ There are cases where Kubernetes resources must be deployed in a specific order.
 For example, you cannot define a resource in a Kubernetes namespace before the
 namespace was created.
 
-You can represent dependencies between `KubernetesResource`s using
+You can represent dependencies between `KubernetesManifest`s using
 `resource.node.addDependency()`:
 
 ```ts
-const namespace = cluster.addResource('my-namespace', {
+const namespace = cluster.addManifest('my-namespace', {
   apiVersion: 'v1',
   kind: 'Namespace',
   metadata: { name: 'my-app' }
 });
 
-const service = cluster.addResource('my-service', {
+const service = cluster.addManifest('my-service', {
   metadata: {
     name: 'myservice',
     namespace: 'my-app'
@@ -377,14 +377,14 @@ const service = cluster.addResource('my-service', {
 service.node.addDependency(namespace); // will apply `my-namespace` before `my-service`.
 ```
 
-NOTE: when a `KubernetesResource` includes multiple resources (either directly
-or through `cluster.addResource()`) (e.g. `cluster.addResource('foo', r1, r2,
+NOTE: when a `KubernetesManifest` includes multiple resources (either directly
+or through `cluster.addManifest()`) (e.g. `cluster.addManifest('foo', r1, r2,
 r3,...))`), these resources will be applied as a single manifest via `kubectl`
 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,37 @@ new KubernetesPatch(this, 'hello-kub-deployment-label', {
 })
 ```
 
+### Querying Kubernetes Object Values
+
+The `KubernetesObjectValue` construct can be used to query for information about kubernetes objects,
+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 KubernetesObjectValue(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
+  },
+})
+```
+
+Specifically, since the above use-case is quite common, there is an easier way to access that information:
+
+```typescript
+const loadBalancerAddress = cluster.getServiceLoadBalancerAddress('my-service');
+```
+
 ### 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),
@@ -548,7 +579,7 @@ const sa = cluster.addServiceAccount('MyServiceAccount');
 const bucket = new Bucket(this, 'Bucket');
 bucket.grantReadWrite(serviceAccount);
 
-const mypod = cluster.addResource('mypod', {
+const mypod = cluster.addManifest('mypod', {
   apiVersion: 'v1',
   kind: 'Pod',
   metadata: { name: 'mypod' },

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

@@ -2,7 +2,7 @@ import * as iam from '@aws-cdk/aws-iam';
 import { Construct, Lazy, Stack } from '@aws-cdk/core';
 import { AwsAuthMapping } from './aws-auth-mapping';
 import { Cluster } from './cluster';
-import { KubernetesResource } from './k8s-resource';
+import { KubernetesManifest } from './k8s-manifest';
 
 /**
  * Configuration props for the AwsAuth construct.
@@ -32,7 +32,7 @@ export class AwsAuth extends Construct {
 
     this.stack = Stack.of(this);
 
-    new KubernetesResource(this, 'manifest', {
+    new KubernetesManifest(this, 'manifest', {
       cluster: props.cluster,
       manifest: [
         {

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

@@ -4,15 +4,16 @@ import * as autoscaling from '@aws-cdk/aws-autoscaling';
 import * as ec2 from '@aws-cdk/aws-ec2';
 import * as iam from '@aws-cdk/aws-iam';
 import * as ssm from '@aws-cdk/aws-ssm';
-import { CfnOutput, CfnResource, Construct, IResource, Resource, Stack, Tag, Token } from '@aws-cdk/core';
+import { CfnOutput, CfnResource, Construct, IResource, Resource, Stack, Tag, Token, Duration } from '@aws-cdk/core';
 import * as YAML from 'yaml';
 import { AwsAuth } from './aws-auth';
 import { clusterArnComponents, ClusterResource } from './cluster-resource';
 import { CfnClusterProps } from './eks.generated';
 import { FargateProfile, FargateProfileOptions } from './fargate-profile';
 import { HelmChart, HelmChartOptions } from './helm-chart';
+import { KubernetesManifest } from './k8s-manifest';
+import { KubernetesObjectValue } from './k8s-object-value';
 import { KubernetesPatch } from './k8s-patch';
-import { KubernetesResource } from './k8s-resource';
 import { KubectlProvider, KubectlProviderProps } from './kubectl-provider';
 import { Nodegroup, NodegroupOptions  } from './managed-nodegroup';
 import { ServiceAccount, ServiceAccountOptions } from './service-account';
@@ -416,6 +417,27 @@ export class KubernetesVersion {
   private constructor(public readonly version: string) { }
 }
 
+/**
+ * Options for fetching a ServiceLoadBalancerAddress.
+ */
+export interface ServiceLoadBalancerAddressOptions {
+
+  /**
+   * Timeout for waiting on the load balancer address.
+   *
+   * @default Duration.minutes(5)
+   */
+  readonly timeout?: Duration;
+
+  /**
+   * The namespace the service belongs to.
+   *
+   * @default 'default'
+   */
+  readonly namespace?: string;
+
+}
+
 /**
  * A Cluster represents a managed Kubernetes Service (EKS)
  *
@@ -524,7 +546,7 @@ export class Cluster extends Resource implements ICluster {
 
   private _spotInterruptHandler?: HelmChart;
 
-  private _neuronDevicePlugin?: KubernetesResource;
+  private _neuronDevicePlugin?: KubernetesManifest;
 
   private readonly endpointAccess: EndpointAccess;
 
@@ -714,6 +736,27 @@ export class Cluster extends Resource implements ICluster {
     this.defineCoreDnsComputeType(props.coreDnsComputeType ?? CoreDnsComputeType.EC2);
   }
 
+  /**
+   * Fetch the load balancer address of a service of type 'LoadBalancer'.
+   *
+   * @param serviceName The name of the service.
+   * @param options Additional operation options.
+   */
+  public getServiceLoadBalancerAddress(serviceName: string, options: ServiceLoadBalancerAddressOptions = {}): string {
+
+    const loadBalancerAddress = new KubernetesObjectValue(this, `${serviceName}LoadBalancerAddress`, {
+      cluster: this,
+      objectType: 'service',
+      objectName: serviceName,
+      objectNamespace: options.namespace,
+      jsonPath: '.status.loadBalancer.ingress[0].hostname',
+      timeout: options.timeout,
+    });
+
+    return loadBalancerAddress.value;
+
+  }
+
   /**
    * Add nodes to this EKS cluster
    *
@@ -913,16 +956,16 @@ export class Cluster extends Resource implements ICluster {
   }
 
   /**
-   * Defines a Kubernetes resource in this cluster.
+   * Defines a Kubernetes manifest in this cluster.
    *
    * The manifest will be applied/deleted using kubectl as needed.
    *
    * @param id logical id of this manifest
    * @param manifest a list of Kubernetes resource specifications
-   * @returns a `KubernetesResource` object.
+   * @returns a `KubernetesManifest` object.
    */
-  public addResource(id: string, ...manifest: any[]) {
-    return new KubernetesResource(this, `manifest-${id}`, { cluster: this, manifest });
+  public addManifest(id: string, ...manifest: any[]) {
+    return new KubernetesManifest(this, `manifest-${id}`, { cluster: this, manifest });
   }
 
   /**
@@ -1109,7 +1152,7 @@ export class Cluster extends Resource implements ICluster {
     if (!this._neuronDevicePlugin) {
       const fileContents = fs.readFileSync(path.join(__dirname, 'addons/neuron-device-plugin.yaml'), 'utf8');
       const sanitized = YAML.parse(fileContents);
-      this._neuronDevicePlugin = this.addResource('NeuronDevicePlugin', sanitized);
+      this._neuronDevicePlugin = this.addManifest('NeuronDevicePlugin', sanitized);
     }
 
     return this._neuronDevicePlugin;

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

@@ -6,7 +6,8 @@ export * from './eks.generated';
 export * from './fargate-profile';
 export * from './helm-chart';
 export * from './k8s-patch';
-export * from './k8s-resource';
+export * from './k8s-manifest';
+export * from './k8s-object-value';
 export * from './fargate-cluster';
 export * from './service-account';
 export * from './managed-nodegroup';

packages/@aws-cdk/aws-eks/lib/k8s-resource.ts packages/@aws-cdk/aws-eks/lib/k8s-manifest.ts

@@ -2,63 +2,63 @@ import { Construct, CustomResource, Stack } from '@aws-cdk/core';
 import { Cluster } from './cluster';
 
 /**
- * Properties for KubernetesResources
+ * Properties for KubernetesManifest
  */
-export interface KubernetesResourceProps {
+export interface KubernetesManifestProps {
   /**
-   * The EKS cluster to apply this configuration to.
+   * The EKS cluster to apply this manifest to.
    *
    * [disable-awslint:ref-via-interface]
    */
   readonly cluster: Cluster;
 
   /**
-   * The resource manifest.
+   * The manifest to apply.
    *
    * Consists of any number of child resources.
    *
-   * When the resource is created/updated, this manifest will be applied to the
-   * cluster through `kubectl apply` and when the resource or the stack is
-   * deleted, the manifest will be deleted through `kubectl delete`.
+   * When the resources are created/updated, this manifest will be applied to the
+   * cluster through `kubectl apply` and when the resources or the stack is
+   * deleted, the resources in the manifest will be deleted through `kubectl delete`.
    *
    * @example
    *
-   * {
+   * [{
    *   apiVersion: 'v1',
    *   kind: 'Pod',
    *   metadata: { name: 'mypod' },
    *   spec: {
    *     containers: [ { name: 'hello', image: 'paulbouwer/hello-kubernetes:1.5', ports: [ { containerPort: 8080 } ] } ]
    *   }
-   * }
+   * }]
    *
    */
   readonly manifest: any[];
 }
 
 /**
- * Represents a resource within the Kubernetes system.
+ * Represents a manifest within the Kubernetes system.
  *
- * Alternatively, you can use `cluster.addResource(resource[, resource, ...])`
+ * Alternatively, you can use `cluster.addManifest(resource[, resource, ...])`
  * to define resources on this cluster.
  *
- * Applies/deletes the resources using `kubectl` in sync with the resource.
+ * Applies/deletes the manifest using `kubectl`.
  */
-export class KubernetesResource extends Construct {
+export class KubernetesManifest extends Construct {
   /**
    * The CloudFormation reosurce type.
    */
   public static readonly RESOURCE_TYPE = 'Custom::AWSCDK-EKS-KubernetesResource';
 
-  constructor(scope: Construct, id: string, props: KubernetesResourceProps) {
+  constructor(scope: Construct, id: string, props: KubernetesManifestProps) {
     super(scope, id);
 
     const stack = Stack.of(this);
     const provider = props.cluster._attachKubectlResourceScope(this);
 
     new CustomResource(this, 'Resource', {
       serviceToken: provider.serviceToken,
-      resourceType: KubernetesResource.RESOURCE_TYPE,
+      resourceType: KubernetesManifest.RESOURCE_TYPE,
       properties: {
         // `toJsonString` enables embedding CDK tokens in the manifest and will
         // render a CloudFormation-compatible JSON string (similar to