feat: introduce ClusterApiObject type

src/api-object.ts

@@ -226,7 +226,7 @@ export class ApiObject extends Construct {
  }
 }
 
-function parseApiGroup(apiVersion: string) {
+export function parseApiGroup(apiVersion: string) {
  const v = apiVersion.split('/');
 
  // no group means "core"

src/cluster-api-object.ts

@@ -0,0 +1,155 @@
+import { Construct, IConstruct } from 'constructs';
+import { sanitizeValue } from './_util';
+import { Chart } from './chart';
+import { JsonPatch } from './json-patch';
+import { ClusterApiObjectMetadata, ClusterApiObjectMetadataDefinition } from './cluster-metadata';
+import { resolve } from './resolve';
+import { ApiObject, parseApiGroup } from './api-object';
+
+/**
+ * Options for defining API objects.
+ */
+export interface ClusterApiObjectProps {
+ /**
+ * Object metadata.
+ *
+ * If `name` is not specified, an app-unique name will be allocated by the
+ * framework based on the path of the construct within thes construct tree.
+ */
+ readonly metadata?: ClusterApiObjectMetadata;
+
+ /**
+ * API version.
+ */
+ readonly apiVersion: string;
+
+ /**
+ * Resource kind.
+ */
+ readonly kind: string;
+
+ /**
+ * Additional attributes for this API object.
+ * @jsii ignore
+ * @see https://github.com/cdk8s-team/cdk8s-core/issues/1297
+ */
+ readonly [key: string]: any;
+}
+
+const CLUSTER_API_OBJECT_SYMBOL = Symbol.for('cdk8s.ClusterApiObject');
+
+export class ClusterApiObject extends ApiObject {
+
+ /**
+ * Return whether the given object is an `ClusterApiObject`.
+ *
+ * We do attribute detection since we can't reliably use 'instanceof'.
+
+ * @param o The object to check
+ */
+ static isClusterApiObject(o: any): o is ClusterApiObject {
+ return o !== null && typeof o === 'object' && CLUSTER_API_OBJECT_SYMBOL in o;
+ }
+
+ /**
+ * Implements `instanceof ClusterApiObject` using the more reliable `ClusterApiObject.isClusterApiObject` static method
+ *
+ * @param o The object to check
+ * @internal
+ */
+ static [Symbol.hasInstance](o: unknown) {
+ return ClusterApiObject.isClusterApiObject(o);
+ }
+ /**
+ * Returns the `ApiObject` named `Resource` which is a child of the given
+ * construct. If `c` is an `ApiObject`, it is returned directly. Throws an
+ * exception if the construct does not have a child named `Default` _or_ if
+ * this child is not an `ApiObject`.
+ *
+ * @param c The higher-level construct
+ */
+ public static of(c: IConstruct): ClusterApiObject {
+ if (c instanceof ClusterApiObject) {
+ return c;
+ }
+
+ const child = c.node.defaultChild;
+ if (!child) {
+ throw new Error(`cannot find a (direct or indirect) child of type ClusterApiObject for construct ${c.node.path}`);
+ }
+
+ return ClusterApiObject.of(child);
+ }
+
+ /**
+ * Metadata associated with this API object.
+ */
+ public readonly metadata: ClusterApiObjectMetadataDefinition;
+
+ /**
+ * Defines an API object.
+ *
+ * @param scope the construct scope
+ * @param id namespace
+ * @param props options
+ */
+ constructor(scope: Construct, id: string, private readonly props: ClusterApiObjectProps) {
+ super(scope, id, props);
+ this.patches = new Array<JsonPatch>();
+ this.chart = Chart.of(this);
+ this.kind = props.kind;
+ this.apiVersion = props.apiVersion;
+ this.apiGroup = parseApiGroup(this.apiVersion);
+
+ this.name = props.metadata?.name ?? this.chart.generateObjectName(this);
+
+ this.metadata = new ClusterApiObjectMetadataDefinition({
+ name: this.name,
+
+ // user defined values
+ ...props.metadata,
+
+ labels: {
+ ...this.chart.labels,
+ ...props.metadata?.labels,
+ },
+ clusterApiObject: this,
+ });
+
+ Object.defineProperty(this, CLUSTER_API_OBJECT_SYMBOL, { value: true });
+ }
+
+ /**
+ * Renders the object to Kubernetes JSON.
+ *
+ * To disable sorting of dictionary keys in output object set the
+ * `CDK8S_DISABLE_SORT` environment variable to any non-empty value.
+ */
+ public toJson(): any {
+
+ try {
+ const data: any = {
+ ...this.props,
+ metadata: this.metadata.toJson(),
+ };
+
+ const sortKeys = process.env.CDK8S_DISABLE_SORT ? false : true;
+ const json = sanitizeValue(resolve([], data, this), { sortKeys });
+ const patched = JsonPatch.apply(json, ...this.patches);
+
+ // reorder top-level keys so that we first have "apiVersion", "kind" and
+ // "metadata" and then all the rest
+ const result: any = {};
+ const orderedKeys = ['apiVersion', 'kind', 'metadata', ...Object.keys(patched)];
+ for (const k of orderedKeys) {
+ if (k in patched) {
+ result[k] = patched[k];
+ }
+ }
+
+ return result;
+ } catch (e) {
+ throw new Error(`Failed serializing construct at path '${this.node.path}' with name '${this.name}': ${e}`);
+ }
+ }
+}

src/cluster-metadata.ts

@@ -0,0 +1,62 @@
+import { sanitizeValue } from './_util';
+import { ClusterApiObject } from './cluster-api-object';
+import { ApiObjectMetadata, ApiObjectMetadataDefinition } from './metadata';
+import { resolve } from './resolve';
+
+/**
+ * Metadata associated with this object.
+ */
+export interface ClusterApiObjectMetadata extends Omit<ApiObjectMetadata, 'namespace'> {}
+
+/**
+ * Options for `ApiObjectMetadataDefinition`.
+ */
+export interface ClusterApiObjectMetadataDefinitionOptions extends ClusterApiObjectMetadata {
+
+ /**
+ * Which ApiObject instance is the metadata attached to.
+ */
+ readonly clusterApiObject: ClusterApiObject;
+
+}
+
+/**
+ * Object metadata.
+ */
+export class ClusterApiObjectMetadataDefinition extends ApiObjectMetadataDefinition {
+
+ /**
+ * The ApiObject this metadata is attached to.
+ */
+ private readonly clusterApiObject: ClusterApiObject;
+
+ constructor(options: ClusterApiObjectMetadataDefinitionOptions) {
+ super(options);
+ this.name = options.name;
+ this.labels = { ...options.labels } ?? { };
+ this.annotations = { ...options.annotations } ?? { };
+ this.finalizers = options.finalizers ? [...options.finalizers] : [];
+ this.ownerReferences = options.ownerReferences ? [...options.ownerReferences] : [];
+ this.clusterApiObject = options.clusterApiObject;
+ this._additionalAttributes = options;
+
+ // otherwise apiObject is passed to the resolving logic, which expectadly fails
+ delete this._additionalAttributes.apiObject;
+
+ }
+
+ /**
+ * Synthesizes a k8s ObjectMeta for this metadata set.
+ */
+ public toJson() {
+ const sanitize = (x: any) => sanitizeValue(x, { filterEmptyArrays: true, filterEmptyObjects: true });
+ return sanitize(resolve([], {
+ ...this._additionalAttributes,
+ name: this.name,
+ annotations: this.annotations,
+ finalizers: this.finalizers,
+ ownerReferences: this.ownerReferences,
+ labels: this.labels,
+ }, this.clusterApiObject));
+ }
+}