Skip to content

cdk8s

Classes

Name Description
ApiObject No description
ApiObjectMetadataDefinition Object metadata.
App Represents a cdk8s application.
Chart No description
DependencyGraph Represents the dependency graph for a given Node.
DependencyVertex Represents a vertex in the graph.
Duration Represents a length of time.
Helm Represents a Helm deployment.
Include Reads a YAML manifest from a file or a URL and defines all resources as API objects within the defined scope.
JsonPatch Utility for applying RFC-6902 JSON-Patch to a document.
Lazy No description
Names Utilities for generating unique and stable names.
Size Represents the amount of digital storage.
Testing Testing utilities for cdk8s applications.
Yaml YAML utilities.

Structs

Name Description
ApiObjectMetadata Metadata associated with this object.
ApiObjectProps Options for defining API objects.
AppProps No description
ChartProps No description
HelmProps Options for Helm.
IncludeProps No description
NameOptions Options for name generation.
SizeConversionOptions Options for how to convert time to a different unit.
TimeConversionOptions Options for how to convert time to a different unit.

Interfaces

Name Description
IAnyProducer No description

Enums

Name Description
SizeRoundingBehavior Rounding behaviour when converting between units of Size.

class ApiObject ๐Ÿ”น

Implements: IConstruct Extends: Construct

Initializer

Defines an API object.

new ApiObject(scope: Construct, id: string, props: ApiObjectProps)
  • scope (Construct) the construct scope.
  • id (string) namespace.
  • props (ApiObjectProps) options.
  • apiVersion (string) API version.
  • kind (string) Resource kind.
  • metadata (ApiObjectMetadata) Object metadata. Optional

Properties

Name Type Description
apiGroup๐Ÿ”น string The group portion of the API version (e.g. authorization.k8s.io).
apiVersion๐Ÿ”น string The object’s API version (e.g. authorization.k8s.io/v1).
chart๐Ÿ”น Chart The chart in which this object is defined.
kind๐Ÿ”น string The object kind.
metadata๐Ÿ”น ApiObjectMetadataDefinition Metadata associated with this API object.
name๐Ÿ”น string The name of the API object.

Methods

addDependency(…dependencies)๐Ÿ”น

Create a dependency between this ApiObject and other constructs.

These can be other ApiObjects, Charts, or custom.

addDependency(...dependencies: IConstruct[]): void
  • dependencies (IConstruct) the dependencies to add.

addJsonPatch(…ops)๐Ÿ”น

Applies a set of RFC-6902 JSON-Patch operations to the manifest synthesized for this API object.

addJsonPatch(...ops: JsonPatch[]): void
  • ops (JsonPatch) The JSON-Patch operations to apply.

toJson()๐Ÿ”น

Renders the object to Kubernetes JSON.

toJson(): any

Returns: * any

static of(c)๐Ÿ”น

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.

static of(c: IConstruct): ApiObject

Returns: * ApiObject

class ApiObjectMetadataDefinition ๐Ÿ”น

Object metadata.

Initializer

new ApiObjectMetadataDefinition(options?: ApiObjectMetadata)
  • options (ApiObjectMetadata) No description
  • annotations (Map) Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. Default: No annotations.
  • labels (Map) Map of string keys and values that can be used to organize and categorize (scope and select) objects. Default: No labels.
  • name (string) The unique, namespace-global, name of this object inside the Kubernetes cluster. Default: an app-unique name generated by the chart
  • namespace (string) Namespace defines the space within each name must be unique. Default: undefined (will be assigned to the ‘default’ namespace)

Properties

Name Type Description
name?๐Ÿ”น string The name of the API object.
Optional
namespace?๐Ÿ”น string The object’s namespace.
Optional

Methods

add(key, value)๐Ÿ”น

Adds an arbitrary key/value to the object metadata.

add(key: string, value: any): void
  • key (string) Metadata key.
  • value (any) Metadata value.

addAnnotation(key, value)๐Ÿ”น

Add an annotation.

addAnnotation(key: string, value: string): void
  • key (string) - The key.
  • value (string) - The value.

addLabel(key, value)๐Ÿ”น

Add a label.

addLabel(key: string, value: string): void
  • key (string) - The key.
  • value (string) - The value.

getLabel(key)๐Ÿ”น

getLabel(key: string): string
  • key (string) the label.

Returns: * string

toJson()๐Ÿ”น

Synthesizes a k8s ObjectMeta for this metadata set.

toJson(): any

Returns: * any

class App ๐Ÿ”น

Represents a cdk8s application.

Implements: IConstruct Extends: Construct

Initializer

Defines an app.

new App(props?: AppProps)
  • props (AppProps) configuration options.
  • outdir (string) The directory to output Kubernetes manifests. Default: CDK8S_OUTDIR if defined, otherwise “dist”

Properties

Name Type Description
outdir๐Ÿ”น string The output directory into which manifests will be synthesized.

Methods

synth()๐Ÿ”น

Synthesizes all manifests to the output directory.

synth(): void

class Chart ๐Ÿ”น

Implements: IConstruct Extends: Construct

Initializer

new Chart(scope: Construct, id: string, props?: ChartProps)
  • scope (Construct) No description
  • id (string) No description
  • props (ChartProps) No description
  • labels (Map) Labels to apply to all resources in this chart. Default: no common labels
  • namespace (string) The default namespace for all objects defined in this chart (directly or indirectly). Default: no namespace is synthesized (usually this implies “default”)

Properties

Name Type Description
labels๐Ÿ”น Map Labels applied to all resources in this chart.
namespace?๐Ÿ”น string The default namespace for all objects in this chart.
Optional

Methods

addDependency(…dependencies)๐Ÿ”น

Create a dependency between this Chart and other constructs.

These can be other ApiObjects, Charts, or custom.

addDependency(...dependencies: IConstruct[]): void
  • dependencies (IConstruct) the dependencies to add.

generateObjectName(apiObject)๐Ÿ”น

Generates a app-unique name for an object given it’s construct node path.

Different resource types may have different constraints on names (metadata.name). The previous version of the name generator was compatible with DNS_SUBDOMAIN but not with DNS_LABEL.

For example, Deployment names must comply with DNS_SUBDOMAIN while Service names must comply with DNS_LABEL.

Since there is no formal specification for this, the default name generation scheme for kubernetes objects in cdk8s was changed to DNS_LABEL, since itโ€™s the common denominator for all kubernetes resources (supposedly).

You can override this method if you wish to customize object names at the chart level.

generateObjectName(apiObject: ApiObject): string
  • apiObject (ApiObject) The API object to generate a name for.

Returns: * string

toJson()๐Ÿ”น

Renders this chart to a set of Kubernetes JSON resources.

toJson(): Array<any>

Returns: * Array

static of(c)๐Ÿ”น

Finds the chart in which a node is defined.

static of(c: IConstruct): Chart

Returns: * Chart

class DependencyGraph ๐Ÿ”น

Represents the dependency graph for a given Node.

This graph includes the dependency relationships between all nodes in the node (construct) sub-tree who’s root is this Node.

Note that this means that lonely nodes (no dependencies and no dependants) are also included in this graph as childless children of the root node of the graph.

The graph does not include cross-scope dependencies. That is, if a child on the current scope depends on a node from a different scope, that relationship is not represented in this graph.

Initializer

new DependencyGraph(node: Node)
  • node (Node) No description

Properties

Name Type Description
root๐Ÿ”น DependencyVertex Returns the root of the graph.

Methods

topology()๐Ÿ”น

topology(): Array<IConstruct>

Returns: * Array<IConstruct>

class DependencyVertex ๐Ÿ”น

Represents a vertex in the graph.

The value of each vertex is an IConstruct that is accessible via the .value getter.

Initializer

new DependencyVertex(value?: IConstruct)

Properties

Name Type Description
inbound๐Ÿ”น Array<DependencyVertex> Returns the parents of the vertex (i.e dependants).
outbound๐Ÿ”น Array<DependencyVertex> Returns the children of the vertex (i.e dependencies).
value?๐Ÿ”น IConstruct Returns the IConstruct this graph vertex represents.
Optional

Methods

addChild(dep)๐Ÿ”น

Adds a vertex as a dependency of the current node.

Also updates the parents of dep, so that it contains this node as a parent.

This operation will fail in case it creates a cycle in the graph.

addChild(dep: DependencyVertex): void

topology()๐Ÿ”น

Returns a topologically sorted array of the constructs in the sub-graph.

topology(): Array<IConstruct>

Returns: * Array<IConstruct>

class Duration ๐Ÿ”น

Represents a length of time.

The amount can be specified either as a literal value (e.g: 10) which cannot be negative.

Methods

toDays(opts?)๐Ÿ”น

Return the total number of days in this Duration.

toDays(opts?: TimeConversionOptions): number
  • opts (TimeConversionOptions) No description
  • integral (boolean) If true, conversions into a larger time unit (e.g. Seconds to Minutes) will fail if the result is not an integer. Default: true

Returns: * number

toHours(opts?)๐Ÿ”น

Return the total number of hours in this Duration.

toHours(opts?: TimeConversionOptions): number
  • opts (TimeConversionOptions) No description
  • integral (boolean) If true, conversions into a larger time unit (e.g. Seconds to Minutes) will fail if the result is not an integer. Default: true

Returns: * number

toHumanString()๐Ÿ”น

Turn this duration into a human-readable string.

toHumanString(): string

Returns: * string

toISOString()โš ๏ธ

Return an ISO 8601 representation of this period.

toISOString(): string

Returns: * string

toIsoString()๐Ÿ”น

Return an ISO 8601 representation of this period.

toIsoString(): string

Returns: * string

toMilliseconds(opts?)๐Ÿ”น

Return the total number of milliseconds in this Duration.

toMilliseconds(opts?: TimeConversionOptions): number
  • opts (TimeConversionOptions) No description
  • integral (boolean) If true, conversions into a larger time unit (e.g. Seconds to Minutes) will fail if the result is not an integer. Default: true

Returns: * number

toMinutes(opts?)๐Ÿ”น

Return the total number of minutes in this Duration.

toMinutes(opts?: TimeConversionOptions): number
  • opts (TimeConversionOptions) No description
  • integral (boolean) If true, conversions into a larger time unit (e.g. Seconds to Minutes) will fail if the result is not an integer. Default: true

Returns: * number

toSeconds(opts?)๐Ÿ”น

Return the total number of seconds in this Duration.

toSeconds(opts?: TimeConversionOptions): number
  • opts (TimeConversionOptions) No description
  • integral (boolean) If true, conversions into a larger time unit (e.g. Seconds to Minutes) will fail if the result is not an integer. Default: true

Returns: * number

static days(amount)๐Ÿ”น

Create a Duration representing an amount of days.

static days(amount: number): Duration
  • amount (number) the amount of Days the Duration will represent.

Returns: * Duration

static hours(amount)๐Ÿ”น

Create a Duration representing an amount of hours.

static hours(amount: number): Duration
  • amount (number) the amount of Hours the Duration will represent.

Returns: * Duration

static millis(amount)๐Ÿ”น

Create a Duration representing an amount of milliseconds.

static millis(amount: number): Duration
  • amount (number) the amount of Milliseconds the Duration will represent.

Returns: * Duration

static minutes(amount)๐Ÿ”น

Create a Duration representing an amount of minutes.

static minutes(amount: number): Duration
  • amount (number) the amount of Minutes the Duration will represent.

Returns: * Duration

static parse(duration)๐Ÿ”น

Parse a period formatted according to the ISO 8601 standard.

static parse(duration: string): Duration
  • duration (string) an ISO-formtted duration to be parsed.

Returns: * Duration

static seconds(amount)๐Ÿ”น

Create a Duration representing an amount of seconds.

static seconds(amount: number): Duration
  • amount (number) the amount of Seconds the Duration will represent.

Returns: * Duration

class Helm ๐Ÿ”น

Represents a Helm deployment.

Use this construct to import an existing Helm chart and incorporate it into your constructs.

Implements: IConstruct Extends: Include

Initializer

new Helm(scope: Construct, id: string, props: HelmProps)
  • scope (Construct) No description
  • id (string) No description
  • props (HelmProps) No description
  • chart (string) The chart name to use. It can be a chart from a helm repository or a local directory.
  • helmExecutable (string) The local helm executable to use in order to create the manifest the chart. Default: “helm”
  • helmFlags (Array) Additional flags to add to the helm execution. Default: []
  • releaseName (string) The release name. Default: if unspecified, a name will be allocated based on the construct path
  • values (Map) Values to pass to the chart. Default: If no values are specified, chart will use the defaults.

Properties

Name Type Description
releaseName๐Ÿ”น string The helm release name.

class Include ๐Ÿ”น

Reads a YAML manifest from a file or a URL and defines all resources as API objects within the defined scope.

The names (metadata.name) of imported resources will be preserved as-is from the manifest.

Implements: IConstruct Extends: Construct

Initializer

new Include(scope: Construct, id: string, props: IncludeProps)
  • scope (Construct) No description
  • id (string) No description
  • props (IncludeProps) No description
  • url (string) Local file path or URL which includes a Kubernetes YAML manifest.

Properties

Name Type Description
apiObjects๐Ÿ”น Array<ApiObject> Returns all the included API objects.

class JsonPatch ๐Ÿ”น

Utility for applying RFC-6902 JSON-Patch to a document.

Use the the JsonPatch.apply(doc, ...ops) function to apply a set of operations to a JSON document and return the result.

Operations can be created using the factory methods JsonPatch.add(), JsonPatch.remove(), etc.

Methods

static add(path, value)๐Ÿ”น

Adds a value to an object or inserts it into an array.

In the case of an array, the value is inserted before the given index. The - character can be used instead of an index to insert at the end of an array.

static add(path: string, value: any): JsonPatch
  • path (string) No description
  • value (any) No description

Returns: * JsonPatch

static apply(document, …ops)๐Ÿ”น

Applies a set of JSON-Patch (RFC-6902) operations to document and returns the result.

static apply(document: any, ...ops: JsonPatch[]): any
  • document (any) The document to patch.
  • ops (JsonPatch) The operations to apply.

Returns: * any

static copy(from, path)๐Ÿ”น

Copies a value from one location to another within the JSON document.

Both from and path are JSON Pointers.

static copy(from: string, path: string): JsonPatch
  • from (string) No description
  • path (string) No description

Returns: * JsonPatch

static move(from, path)๐Ÿ”น

Moves a value from one location to the other.

Both from and path are JSON Pointers.

static move(from: string, path: string): JsonPatch
  • from (string) No description
  • path (string) No description

Returns: * JsonPatch

static remove(path)๐Ÿ”น

Removes a value from an object or array.

static remove(path: string): JsonPatch
  • path (string) No description

Returns: * JsonPatch

static replace(path, value)๐Ÿ”น

Replaces a value.

Equivalent to a โ€œremoveโ€ followed by an โ€œaddโ€.

static replace(path: string, value: any): JsonPatch
  • path (string) No description
  • value (any) No description

Returns: * JsonPatch

static test(path, value)๐Ÿ”น

Tests that the specified value is set in the document.

If the test fails, then the patch as a whole should not apply.

static test(path: string, value: any): JsonPatch
  • path (string) No description
  • value (any) No description

Returns: * JsonPatch

class Lazy ๐Ÿ”น

Methods

produce()๐Ÿ”น

produce(): any

Returns: * any

static any(producer)๐Ÿ”น

static any(producer: IAnyProducer): any

Returns: * any

class Names ๐Ÿ”น

Utilities for generating unique and stable names.

Methods

static toDnsLabel(scope, options?)๐Ÿ”น

Generates a unique and stable name compatible DNS_LABEL from RFC-1123 from a path.

The generated name will: - contain at most 63 characters - contain only lowercase alphanumeric characters or โ€˜-โ€™ - start with an alphanumeric character - end with an alphanumeric character

The generated name will have the form: --..--

Where are the path components (assuming they are is separated by “/”).

Note that if the total length is longer than 63 characters, we will trim the first components since the last components usually encode more meaning.

static toDnsLabel(scope: Construct, options?: NameOptions): string
  • scope (Construct) The construct for which to render the DNS label.
  • options (NameOptions) Name options.
  • delimiter (string) Delimiter to use between components. Default: “-“
  • extra (Array) Extra components to include in the name. Default: [] use the construct path components
  • maxLen (number) Maximum allowed length for the name. Default: 63

Returns: * string

static toLabelValue(scope, options?)๐Ÿ”น

Generates a unique and stable name compatible label key name segment and label value from a path.

The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between.

Valid label values must be 63 characters or less and must be empty or begin and end with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between.

The generated name will have the form: ..

Where are the path components (assuming they are is separated by “/”).

Note that if the total length is longer than 63 characters, we will trim the first components since the last components usually encode more meaning.

static toLabelValue(scope: Construct, options?: NameOptions): string
  • scope (Construct) The construct for which to render the DNS label.
  • options (NameOptions) Name options.
  • delimiter (string) Delimiter to use between components. Default: “-“
  • extra (Array) Extra components to include in the name. Default: [] use the construct path components
  • maxLen (number) Maximum allowed length for the name. Default: 63

Returns: * string

class Size ๐Ÿ”น

Represents the amount of digital storage.

The amount can be specified either as a literal value (e.g: 10) which cannot be negative.

When the amount is passed as a token, unit conversion is not possible.

Methods

toGibibytes(opts?)๐Ÿ”น

Return this storage as a total number of gibibytes.

toGibibytes(opts?: SizeConversionOptions): number

Returns: * number

toKibibytes(opts?)๐Ÿ”น

Return this storage as a total number of kibibytes.

toKibibytes(opts?: SizeConversionOptions): number

Returns: * number

toMebibytes(opts?)๐Ÿ”น

Return this storage as a total number of mebibytes.

toMebibytes(opts?: SizeConversionOptions): number

Returns: * number

toPebibytes(opts?)๐Ÿ”น

Return this storage as a total number of pebibytes.

toPebibytes(opts?: SizeConversionOptions): number

Returns: * number

toTebibytes(opts?)๐Ÿ”น

Return this storage as a total number of tebibytes.

toTebibytes(opts?: SizeConversionOptions): number

Returns: * number

static gibibytes(amount)๐Ÿ”น

Create a Storage representing an amount gibibytes.

1 GiB = 1024 MiB

static gibibytes(amount: number): Size
  • amount (number) No description

Returns: * Size

static kibibytes(amount)๐Ÿ”น

Create a Storage representing an amount kibibytes.

1 KiB = 1024 bytes

static kibibytes(amount: number): Size
  • amount (number) No description

Returns: * Size

static mebibytes(amount)๐Ÿ”น

Create a Storage representing an amount mebibytes.

1 MiB = 1024 KiB

static mebibytes(amount: number): Size
  • amount (number) No description

Returns: * Size

static pebibyte(amount)๐Ÿ”น

Create a Storage representing an amount pebibytes.

1 PiB = 1024 TiB

static pebibyte(amount: number): Size
  • amount (number) No description

Returns: * Size

static tebibytes(amount)๐Ÿ”น

Create a Storage representing an amount tebibytes.

1 TiB = 1024 GiB

static tebibytes(amount: number): Size
  • amount (number) No description

Returns: * Size

class Testing ๐Ÿ”น

Testing utilities for cdk8s applications.

Methods

static app()๐Ÿ”น

Returns an app for testing with the following properties: - Output directory is a temp dir.

static app(): App

Returns: * App

static chart()๐Ÿ”น

static chart(): Chart

Returns: * Chart

static synth(chart)๐Ÿ”น

Returns the Kubernetes manifest synthesized from this chart.

static synth(chart: Chart): Array<any>
  • chart (Chart) No description

Returns: * Array

class Yaml ๐Ÿ”น

YAML utilities.

Methods

static load(urlOrFile)๐Ÿ”น

Downloads a set of YAML documents (k8s manifest for example) from a URL or a file and returns them as javascript objects.

Empty documents are filtered out.

static load(urlOrFile: string): Array<any>
  • urlOrFile (string) a URL of a file path to load from.

Returns: * Array

static save(filePath, docs)๐Ÿ”น

Saves a set of objects as a multi-document YAML file.

static save(filePath: string, docs: Array<any>): void
  • filePath (string) The output path.
  • docs (Array) The set of objects.

static tmp(docs)๐Ÿ”น

Saves a set of YAML documents into a temp file (in /tmp).

static tmp(docs: Array<any>): string
  • docs (Array) the set of documents to save.

Returns: * string

struct ApiObjectMetadata ๐Ÿ”น

Metadata associated with this object.

Name Type Description
annotations?๐Ÿ”น Map Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata.
Default: No annotations.
labels?๐Ÿ”น Map Map of string keys and values that can be used to organize and categorize (scope and select) objects.
Default: No labels.
name?๐Ÿ”น string The unique, namespace-global, name of this object inside the Kubernetes cluster.
Default: an app-unique name generated by the chart
namespace?๐Ÿ”น string Namespace defines the space within each name must be unique.
Default: undefined (will be assigned to the ‘default’ namespace)

struct ApiObjectProps ๐Ÿ”น

Options for defining API objects.

Name Type Description
apiVersion๐Ÿ”น string API version.
kind๐Ÿ”น string Resource kind.
metadata?๐Ÿ”น ApiObjectMetadata Object metadata.
Optional

struct AppProps ๐Ÿ”น

Name Type Description
outdir?๐Ÿ”น string The directory to output Kubernetes manifests.
Default: CDK8S_OUTDIR if defined, otherwise “dist”

struct ChartProps ๐Ÿ”น

Name Type Description
labels?๐Ÿ”น Map Labels to apply to all resources in this chart.
Default: no common labels
namespace?๐Ÿ”น string The default namespace for all objects defined in this chart (directly or indirectly).
Default: no namespace is synthesized (usually this implies “default”)

struct HelmProps ๐Ÿ”น

Options for Helm.

Name Type Description
chart๐Ÿ”น string The chart name to use. It can be a chart from a helm repository or a local directory.
helmExecutable?๐Ÿ”น string The local helm executable to use in order to create the manifest the chart.
Default: “helm”
helmFlags?๐Ÿ”น Array Additional flags to add to the helm execution.
Default: []
releaseName?๐Ÿ”น string The release name.
Default: if unspecified, a name will be allocated based on the construct path
values?๐Ÿ”น Map Values to pass to the chart.
Default: If no values are specified, chart will use the defaults.

interface IAnyProducer ๐Ÿ”น

Methods

produce()๐Ÿ”น

produce(): any

Returns: * any

struct IncludeProps ๐Ÿ”น

Name Type Description
url๐Ÿ”น string Local file path or URL which includes a Kubernetes YAML manifest.

struct NameOptions ๐Ÿ”น

Options for name generation.

Name Type Description
delimiter?๐Ÿ”น string Delimiter to use between components.
Default: “-“
extra?๐Ÿ”น Array Extra components to include in the name.
Default: [] use the construct path components
maxLen?๐Ÿ”น number Maximum allowed length for the name.
Default: 63

struct SizeConversionOptions ๐Ÿ”น

Options for how to convert time to a different unit.

Name Type Description
rounding?๐Ÿ”น SizeRoundingBehavior How conversions should behave when it encounters a non-integer result.
Default: SizeRoundingBehavior.FAIL

struct TimeConversionOptions ๐Ÿ”น

Options for how to convert time to a different unit.

Name Type Description
integral?๐Ÿ”น boolean If true, conversions into a larger time unit (e.g. Seconds to Minutes) will fail if the result is not an integer.
Default: true

enum SizeRoundingBehavior ๐Ÿ”น

Rounding behaviour when converting between units of Size.

Name Description
FAIL ๐Ÿ”น Fail the conversion if the result is not an integer.
FLOOR ๐Ÿ”น If the result is not an integer, round it to the closest integer less than the result.
NONE ๐Ÿ”น Don’t round.