Skip to content

cdk8s (Python)

Constructs

ApiObject

Initializers

import cdk8s

cdk8s.ApiObject(
  scope: Construct,
  id: str,
  api_version: str,
  kind: str,
  metadata: ApiObjectMetadata = None
)
scopeRequired

the construct scope.


idRequired
  • Type: str

namespace.


api_versionRequired
  • Type: str

API version.


kindRequired
  • Type: str

Resource kind.


metadataOptional

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.


Methods

add_dependency
def add_dependency(
  dependencies: IConstruct
)
dependenciesRequired

the dependencies to add.


add_json_patch
def add_json_patch(
  ops: JsonPatch
)
opsRequired

The JSON-Patch operations to apply.


to_json
def to_json()

Static Functions

of
import cdk8s

cdk8s.ApiObject.of(
  c: IConstruct
)
cRequired

The higher-level construct.


Properties

api_groupRequired
api_group: str
  • Type: str

The group portion of the API version (e.g. authorization.k8s.io).


api_versionRequired
api_version: str
  • Type: str

The object’s API version (e.g. authorization.k8s.io/v1).


chartRequired
chart: Chart

The chart in which this object is defined.


kindRequired
kind: str
  • Type: str

The object kind.


metadataRequired
metadata: ApiObjectMetadataDefinition

Metadata associated with this API object.


nameRequired
name: str
  • Type: str

The name of the API object.

If a name is specified in metadata.name this will be the name returned. Otherwise, a name will be generated by calling Chart.of(this).generatedObjectName(this), which by default uses the construct path to generate a DNS-compatible name for the resource.


App

Represents a cdk8s application.

Initializers

import cdk8s

cdk8s.App(
  outdir: str = None,
  yaml_output_type: YamlOutputType = None
)
outdirOptional
  • Type: str
  • Default: CDK8S_OUTDIR if defined, otherwise “dist”

The directory to output Kubernetes manifests.


yaml_output_typeOptional

How to divide the YAML output into files.


Methods

synth
def synth()

Properties

outdirRequired
outdir: str
  • Type: str

The output directory into which manifests will be synthesized.


yaml_output_typeRequired
yaml_output_type: YamlOutputType

How to divide the YAML output into files.


Chart

Initializers

import cdk8s

cdk8s.Chart(
  scope: Construct,
  id: str,
  labels: typing.Mapping[str] = None,
  namespace: str = None
)
scopeRequired

idRequired
  • Type: str

labelsOptional
  • Type: typing.Mapping[str]
  • Default: no common labels

Labels to apply to all resources in this chart.


namespaceOptional
  • Type: str
  • Default: no namespace is synthesized (usually this implies “default”)

The default namespace for all objects defined in this chart (directly or indirectly).

This namespace will only apply to objects that don’t have a namespace explicitly defined for them.


Methods

add_dependency
def add_dependency(
  dependencies: IConstruct
)
dependenciesRequired

the dependencies to add.


generate_object_name
def generate_object_name(
  api_object: ApiObject
)
api_objectRequired

The API object to generate a name for.


to_json
def to_json()

Static Functions

of
import cdk8s

cdk8s.Chart.of(
  c: IConstruct
)
cRequired

a construct node.


Properties

labelsRequired
labels: typing.Mapping[str]
  • Type: typing.Mapping[str]

Labels applied to all resources in this chart.

This is an immutable copy.


namespaceOptional
namespace: str
  • Type: str

The default namespace for all objects in this chart.


Helm

Represents a Helm deployment.

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

Initializers

import cdk8s

cdk8s.Helm(
  scope: Construct,
  id: str,
  chart: str,
  helm_executable: str = None,
  helm_flags: typing.List[str] = None,
  release_name: str = None,
  values: typing.Mapping[typing.Any] = None
)
scopeRequired

idRequired
  • Type: str

chartRequired
  • Type: str

The chart name to use. It can be a chart from a helm repository or a local directory.

This name is passed to helm template and has all the relevant semantics.


helm_executableOptional
  • Type: str
  • Default: “helm”

The local helm executable to use in order to create the manifest the chart.


helm_flagsOptional
  • Type: typing.List[str]
  • Default: []

Additional flags to add to the helm execution.


release_nameOptional
  • Type: str
  • Default: if unspecified, a name will be allocated based on the construct path

The release name.

https://helm.sh/docs/intro/using_helm/#three-big-concepts


valuesOptional
  • Type: typing.Mapping[typing.Any]
  • Default: If no values are specified, chart will use the defaults.

Values to pass to the chart.


Properties

release_nameRequired
release_name: str
  • Type: str

The helm release name.


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.

Initializers

import cdk8s

cdk8s.Include(
  scope: Construct,
  id: str,
  url: str
)
scopeRequired

idRequired
  • Type: str

urlRequired
  • Type: str

Local file path or URL which includes a Kubernetes YAML manifest.


Properties

api_objectsRequired
api_objects: typing.List[ApiObject]

Returns all the included API objects.


Structs

ApiObjectMetadata

Metadata associated with this object.

Initializer

import cdk8s

cdk8s.ApiObjectMetadata(
  annotations: typing.Mapping[str] = None,
  labels: typing.Mapping[str] = None,
  name: str = None,
  namespace: str = None
)
annotationsOptional
annotations: typing.Mapping[str]
  • Type: typing.Mapping[str]
  • Default: No annotations.

Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata.

They are not queryable and should be preserved when modifying objects.

http://kubernetes.io/docs/user-guide/annotations


labelsOptional
labels: typing.Mapping[str]
  • Type: typing.Mapping[str]
  • Default: No labels.

Map of string keys and values that can be used to organize and categorize (scope and select) objects.

May match selectors of replication controllers and services.

http://kubernetes.io/docs/user-guide/labels


nameOptional
name: str
  • Type: str
  • Default: an app-unique name generated by the chart

The unique, namespace-global, name of this object inside the Kubernetes cluster.

Normally, you shouldn’t specify names for objects and let the CDK generate a name for you that is application-unique. The names CDK generates are composed from the construct path components, separated by dots and a suffix that is based on a hash of the entire path, to ensure uniqueness.

You can supply custom name allocation logic by overriding the chart.generateObjectName method.

If you use an explicit name here, bear in mind that this reduces the composability of your construct because it won’t be possible to include more than one instance in any app. Therefore it is highly recommended to leave this unspecified.


namespaceOptional
namespace: str
  • Type: str
  • Default: undefined (will be assigned to the ‘default’ namespace)

Namespace defines the space within each name must be unique.

An empty namespace is equivalent to the “default” namespace, but “default” is the canonical representation. Not all objects are required to be scoped to a namespace - the value of this field for those objects will be empty. Must be a DNS_LABEL. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/namespaces


ApiObjectProps

Options for defining API objects.

Initializer

import cdk8s

cdk8s.ApiObjectProps(
  api_version: str,
  kind: str,
  metadata: ApiObjectMetadata = None
)
api_versionRequired
api_version: str
  • Type: str

API version.


kindRequired
kind: str
  • Type: str

Resource kind.


metadataOptional
metadata: ApiObjectMetadata

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.


AppProps

Initializer

import cdk8s

cdk8s.AppProps(
  outdir: str = None,
  yaml_output_type: YamlOutputType = None
)
outdirOptional
outdir: str
  • Type: str
  • Default: CDK8S_OUTDIR if defined, otherwise “dist”

The directory to output Kubernetes manifests.


yaml_output_typeOptional
yaml_output_type: YamlOutputType

How to divide the YAML output into files.


ChartProps

Initializer

import cdk8s

cdk8s.ChartProps(
  labels: typing.Mapping[str] = None,
  namespace: str = None
)
labelsOptional
labels: typing.Mapping[str]
  • Type: typing.Mapping[str]
  • Default: no common labels

Labels to apply to all resources in this chart.


namespaceOptional
namespace: str
  • Type: str
  • Default: no namespace is synthesized (usually this implies “default”)

The default namespace for all objects defined in this chart (directly or indirectly).

This namespace will only apply to objects that don’t have a namespace explicitly defined for them.


GroupVersionKind

Initializer

import cdk8s

cdk8s.GroupVersionKind(
  api_version: str,
  kind: str
)
api_versionRequired
api_version: str
  • Type: str

The object’s API version (e.g. authorization.k8s.io/v1).


kindRequired
kind: str
  • Type: str

The object kind.


HelmProps

Options for Helm.

Initializer

import cdk8s

cdk8s.HelmProps(
  chart: str,
  helm_executable: str = None,
  helm_flags: typing.List[str] = None,
  release_name: str = None,
  values: typing.Mapping[typing.Any] = None
)
chartRequired
chart: str
  • Type: str

The chart name to use. It can be a chart from a helm repository or a local directory.

This name is passed to helm template and has all the relevant semantics.


helm_executableOptional
helm_executable: str
  • Type: str
  • Default: “helm”

The local helm executable to use in order to create the manifest the chart.


helm_flagsOptional
helm_flags: typing.List[str]
  • Type: typing.List[str]
  • Default: []

Additional flags to add to the helm execution.


release_nameOptional
release_name: str
  • Type: str
  • Default: if unspecified, a name will be allocated based on the construct path

The release name.

https://helm.sh/docs/intro/using_helm/#three-big-concepts


valuesOptional
values: typing.Mapping[typing.Any]
  • Type: typing.Mapping[typing.Any]
  • Default: If no values are specified, chart will use the defaults.

Values to pass to the chart.


IncludeProps

Initializer

import cdk8s

cdk8s.IncludeProps(
  url: str
)
urlRequired
url: str
  • Type: str

Local file path or URL which includes a Kubernetes YAML manifest.


NameOptions

Options for name generation.

Initializer

import cdk8s

cdk8s.NameOptions(
  delimiter: str = None,
  extra: typing.List[str] = None,
  include_hash: bool = None,
  max_len: typing.Union[int, float] = None
)
delimiterOptional
delimiter: str
  • Type: str
  • Default: “-“

Delimiter to use between components.


extraOptional
extra: typing.List[str]
  • Type: typing.List[str]
  • Default: [] use the construct path components

Extra components to include in the name.


include_hashOptional
include_hash: bool
  • Type: bool
  • Default: true

Include a short hash as last part of the name.


max_lenOptional
max_len: typing.Union[int, float]
  • Type: typing.Union[int, float]
  • Default: 63

Maximum allowed length for the name.


SizeConversionOptions

Options for how to convert time to a different unit.

Initializer

import cdk8s

cdk8s.SizeConversionOptions(
  rounding: SizeRoundingBehavior = None
)
roundingOptional
rounding: SizeRoundingBehavior

How conversions should behave when it encounters a non-integer result.


TimeConversionOptions

Options for how to convert time to a different unit.

Initializer

import cdk8s

cdk8s.TimeConversionOptions(
  integral: bool = None
)
integralOptional
integral: bool
  • Type: bool
  • Default: true

If true, conversions into a larger time unit (e.g. Seconds to Minutes) will fail if the result is not an integer.


Classes

ApiObjectMetadataDefinition

Object metadata.

Initializers

import cdk8s

cdk8s.ApiObjectMetadataDefinition(
  annotations: typing.Mapping[str] = None,
  labels: typing.Mapping[str] = None,
  name: str = None,
  namespace: str = None
)
annotationsOptional
  • Type: typing.Mapping[str]
  • Default: No annotations.

Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata.

They are not queryable and should be preserved when modifying objects.

http://kubernetes.io/docs/user-guide/annotations


labelsOptional
  • Type: typing.Mapping[str]
  • Default: No labels.

Map of string keys and values that can be used to organize and categorize (scope and select) objects.

May match selectors of replication controllers and services.

http://kubernetes.io/docs/user-guide/labels


nameOptional
  • Type: str
  • Default: an app-unique name generated by the chart

The unique, namespace-global, name of this object inside the Kubernetes cluster.

Normally, you shouldn’t specify names for objects and let the CDK generate a name for you that is application-unique. The names CDK generates are composed from the construct path components, separated by dots and a suffix that is based on a hash of the entire path, to ensure uniqueness.

You can supply custom name allocation logic by overriding the chart.generateObjectName method.

If you use an explicit name here, bear in mind that this reduces the composability of your construct because it won’t be possible to include more than one instance in any app. Therefore it is highly recommended to leave this unspecified.


namespaceOptional
  • Type: str
  • Default: undefined (will be assigned to the ‘default’ namespace)

Namespace defines the space within each name must be unique.

An empty namespace is equivalent to the “default” namespace, but “default” is the canonical representation. Not all objects are required to be scoped to a namespace - the value of this field for those objects will be empty. Must be a DNS_LABEL. Cannot be updated. More info: http://kubernetes.io/docs/user-guide/namespaces


Methods

add
def add(
  key: str,
  value: typing.Any
)
keyRequired
  • Type: str

Metadata key.


valueRequired
  • Type: typing.Any

Metadata value.


add_annotation
def add_annotation(
  key: str,
  value: str
)
keyRequired
  • Type: str

The key.


valueRequired
  • Type: str

The value.


add_label
def add_label(
  key: str,
  value: str
)
keyRequired
  • Type: str

The key.


valueRequired
  • Type: str

The value.


get_label
def get_label(
  key: str
)
keyRequired
  • Type: str

the label.


to_json
def to_json()

Properties

nameOptional
name: str
  • Type: str

The name of the API object.

If a name is specified in metadata.name this will be the name returned. Otherwise, a name will be generated by calling Chart.of(this).generatedObjectName(this), which by default uses the construct path to generate a DNS-compatible name for the resource.


namespaceOptional
namespace: str
  • Type: str

The object’s namespace.


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.

Initializers

import cdk8s

cdk8s.DependencyGraph(
  node: Node
)
nodeRequired

Methods

topology
def topology()

Properties

rootRequired
root: DependencyVertex

Returns the root of the graph.

Note that this vertex will always have null as its .value since it is an artifical root that binds all the connected spaces of the graph.


DependencyVertex

Represents a vertex in the graph.

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

Initializers

import cdk8s

cdk8s.DependencyVertex(
  value: IConstruct = None
)
valueOptional

Methods

add_child
def add_child(
  dep: DependencyVertex
)
depRequired

The dependency.


topology
def topology()

Properties

inboundRequired
inbound: typing.List[DependencyVertex]

Returns the parents of the vertex (i.e dependants).


outboundRequired
outbound: typing.List[DependencyVertex]

Returns the children of the vertex (i.e dependencies).


valueOptional
value: IConstruct

Returns the IConstruct this graph vertex represents.

null in case this is the root of the graph.


Duration

Represents a length of time.

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

Methods

to_days
def to_days(
  integral: bool = None
)
integralOptional
  • Type: bool
  • Default: true

If true, conversions into a larger time unit (e.g. Seconds to Minutes) will fail if the result is not an integer.


to_hours
def to_hours(
  integral: bool = None
)
integralOptional
  • Type: bool
  • Default: true

If true, conversions into a larger time unit (e.g. Seconds to Minutes) will fail if the result is not an integer.


to_human_string
def to_human_string()
to_iso_string
def to_iso_string()
to_milliseconds
def to_milliseconds(
  integral: bool = None
)
integralOptional
  • Type: bool
  • Default: true

If true, conversions into a larger time unit (e.g. Seconds to Minutes) will fail if the result is not an integer.


to_minutes
def to_minutes(
  integral: bool = None
)
integralOptional
  • Type: bool
  • Default: true

If true, conversions into a larger time unit (e.g. Seconds to Minutes) will fail if the result is not an integer.


to_seconds
def to_seconds(
  integral: bool = None
)
integralOptional
  • Type: bool
  • Default: true

If true, conversions into a larger time unit (e.g. Seconds to Minutes) will fail if the result is not an integer.


Static Functions

days
import cdk8s

cdk8s.Duration.days(
  amount: typing.Union[int, float]
)
amountRequired
  • Type: typing.Union[int, float]

the amount of Days the Duration will represent.


hours
import cdk8s

cdk8s.Duration.hours(
  amount: typing.Union[int, float]
)
amountRequired
  • Type: typing.Union[int, float]

the amount of Hours the Duration will represent.


millis
import cdk8s

cdk8s.Duration.millis(
  amount: typing.Union[int, float]
)
amountRequired
  • Type: typing.Union[int, float]

the amount of Milliseconds the Duration will represent.


minutes
import cdk8s

cdk8s.Duration.minutes(
  amount: typing.Union[int, float]
)
amountRequired
  • Type: typing.Union[int, float]

the amount of Minutes the Duration will represent.


parse
import cdk8s

cdk8s.Duration.parse(
  duration: str
)
durationRequired
  • Type: str

an ISO-formtted duration to be parsed.


seconds
import cdk8s

cdk8s.Duration.seconds(
  amount: typing.Union[int, float]
)
amountRequired
  • Type: typing.Union[int, float]

the amount of Seconds the Duration will represent.


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.

Static Functions

add
import cdk8s

cdk8s.JsonPatch.add(
  path: str,
  value: typing.Any
)
pathRequired
  • Type: str

valueRequired
  • Type: typing.Any

apply
import cdk8s

cdk8s.JsonPatch.apply(
  document: typing.Any,
  ops: JsonPatch
)
documentRequired
  • Type: typing.Any

The document to patch.


opsRequired

The operations to apply.


copy
import cdk8s

cdk8s.JsonPatch.copy(
  from: str,
  path: str
)
fromRequired
  • Type: str

pathRequired
  • Type: str

move
import cdk8s

cdk8s.JsonPatch.move(
  from: str,
  path: str
)
fromRequired
  • Type: str

pathRequired
  • Type: str

remove
import cdk8s

cdk8s.JsonPatch.remove(
  path: str
)
pathRequired
  • Type: str

replace
import cdk8s

cdk8s.JsonPatch.replace(
  path: str,
  value: typing.Any
)
pathRequired
  • Type: str

valueRequired
  • Type: typing.Any

test
import cdk8s

cdk8s.JsonPatch.test(
  path: str,
  value: typing.Any
)
pathRequired
  • Type: str

valueRequired
  • Type: typing.Any

Lazy

Methods

produce
def produce()

Static Functions

any
import cdk8s

cdk8s.Lazy.any(
  producer: IAnyProducer
)
producerRequired

Names

Utilities for generating unique and stable names.

Static Functions

to_dns_label
import cdk8s

cdk8s.Names.to_dns_label(
  scope: Construct,
  delimiter: str = None,
  extra: typing.List[str] = None,
  include_hash: bool = None,
  max_len: typing.Union[int, float] = None
)
scopeRequired

The construct for which to render the DNS label.


delimiterOptional
  • Type: str
  • Default: “-“

Delimiter to use between components.


extraOptional
  • Type: typing.List[str]
  • Default: [] use the construct path components

Extra components to include in the name.


include_hashOptional
  • Type: bool
  • Default: true

Include a short hash as last part of the name.


max_lenOptional
  • Type: typing.Union[int, float]
  • Default: 63

Maximum allowed length for the name.


to_label_value
import cdk8s

cdk8s.Names.to_label_value(
  scope: Construct,
  delimiter: str = None,
  extra: typing.List[str] = None,
  include_hash: bool = None,
  max_len: typing.Union[int, float] = None
)
scopeRequired

The construct for which to render the DNS label.


delimiterOptional
  • Type: str
  • Default: “-“

Delimiter to use between components.


extraOptional
  • Type: typing.List[str]
  • Default: [] use the construct path components

Extra components to include in the name.


include_hashOptional
  • Type: bool
  • Default: true

Include a short hash as last part of the name.


max_lenOptional
  • Type: typing.Union[int, float]
  • Default: 63

Maximum allowed length for the name.


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

to_gibibytes
def to_gibibytes(
  rounding: SizeRoundingBehavior = None
)
roundingOptional

How conversions should behave when it encounters a non-integer result.


to_kibibytes
def to_kibibytes(
  rounding: SizeRoundingBehavior = None
)
roundingOptional

How conversions should behave when it encounters a non-integer result.


to_mebibytes
def to_mebibytes(
  rounding: SizeRoundingBehavior = None
)
roundingOptional

How conversions should behave when it encounters a non-integer result.


to_pebibytes
def to_pebibytes(
  rounding: SizeRoundingBehavior = None
)
roundingOptional

How conversions should behave when it encounters a non-integer result.


to_tebibytes
def to_tebibytes(
  rounding: SizeRoundingBehavior = None
)
roundingOptional

How conversions should behave when it encounters a non-integer result.


Static Functions

gibibytes
import cdk8s

cdk8s.Size.gibibytes(
  amount: typing.Union[int, float]
)
amountRequired
  • Type: typing.Union[int, float]

kibibytes
import cdk8s

cdk8s.Size.kibibytes(
  amount: typing.Union[int, float]
)
amountRequired
  • Type: typing.Union[int, float]

mebibytes
import cdk8s

cdk8s.Size.mebibytes(
  amount: typing.Union[int, float]
)
amountRequired
  • Type: typing.Union[int, float]

pebibyte
import cdk8s

cdk8s.Size.pebibyte(
  amount: typing.Union[int, float]
)
amountRequired
  • Type: typing.Union[int, float]

tebibytes
import cdk8s

cdk8s.Size.tebibytes(
  amount: typing.Union[int, float]
)
amountRequired
  • Type: typing.Union[int, float]

Testing

Testing utilities for cdk8s applications.

Static Functions

app
import cdk8s

cdk8s.Testing.app(
  outdir: str = None,
  yaml_output_type: YamlOutputType = None
)
outdirOptional
  • Type: str
  • Default: CDK8S_OUTDIR if defined, otherwise “dist”

The directory to output Kubernetes manifests.


yaml_output_typeOptional

How to divide the YAML output into files.


chart
import cdk8s

cdk8s.Testing.chart()
synth
import cdk8s

cdk8s.Testing.synth(
  chart: Chart
)
chartRequired

Yaml

YAML utilities.

Static Functions

load
import cdk8s

cdk8s.Yaml.load(
  url_or_file: str
)
url_or_fileRequired
  • Type: str

a URL of a file path to load from.


save
import cdk8s

cdk8s.Yaml.save(
  file_path: str,
  docs: typing.List[typing.Any]
)
file_pathRequired
  • Type: str

The output path.


docsRequired
  • Type: typing.List[typing.Any]

The set of objects.


stringify
import cdk8s

cdk8s.Yaml.stringify(
  doc: typing.Any
)
docRequired
  • Type: typing.Any

An object.


tmp
import cdk8s

cdk8s.Yaml.tmp(
  docs: typing.List[typing.Any]
)
docsRequired
  • Type: typing.List[typing.Any]

the set of documents to save.


Protocols

IAnyProducer

Methods

produce
def produce()

Enums

SizeRoundingBehavior

Rounding behaviour when converting between units of Size.

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.

Return even if the result is a fraction.


YamlOutputType

The method to divide YAML output into files.

FILE_PER_APP

All resources are output into a single YAML file.


FILE_PER_CHART

Resources are split into seperate files by chart.


FILE_PER_RESOURCE

Each resource is output to its own file.