KubeDirectorApp Definition

This page documents the v1beta1 KubeDirectorApp data structure.

KubeDirectorApp is a definition of an application type, which can then be instantiated into virtual clusters using KubeDirectorCluster.

Once a KubeDirectorApp resource is created, it can be freely modified or deleted unless a current KubeDirectorCluster resource refers to it. While such a reference exists the KubeDirectorApp resource is immutable.

Miscellaneous Components

These fundamental types are the building blocks of the major elements below.

Endpoint

Field	Description
port integer	The port number where a service can be accessed.
urlScheme string	A well-known description of the protocol used to access the service. For user/client-informational purposes only. Optional. Examples: "https", "spark"
path string	A path used to access http/https (or similar) service endpoints, if the service is not at the "root" exposed at its port. For user/client-informational purposes only. Optional.
isDashboard boolean	Whether the service port+path is intended to be viewed in a web browser. For user/client-informational purposes only. Optional: defaults to false.
	properties supported by KD v0.5.0+ below
hasAuthToken boolean	Whether to generate a UUID for any member exposing this service, for use in simple authentication to this service. See the description of the authToken property in the KD cluster per-member status, for more info about how the generated token is advertised. Optional: defaults to false.

Label

Field	Description
name string	Short name. Must be non-empty.
description string	Long descriptive phrase. Optional.

ConfigPackage

Field	Description
packageURL string	An app setup package to be downloaded from an http(s) service that is accessible to the k8s container network, or taken from a filepath in the container image's filesystem. Pattern: `^(file\|https?)://.+\.tgz$`
	properties supported by KD v0.8.0+ below
useNewSetupLayout boolean	Whether this setup package will function correctly when using the "new layout" for setup packages and persistent storage directories. Although this is false by default for compatibility, it is recommended to set this to true if possible, especially for new app development. See the app-filesystem-layout.md doc for more details. Optional: defaults to false.

ContainerSpec

Field	Description
stdin boolean	Corresponds to setting stdin in the Container for a role member.
tty boolean	Corresponds to setting tty in the Container for a role member. Note that setting tty true also requires setting stdin true.

MinPersistentStorageSpec

Field	Description
size string	Minimum valid size of the requested persistent storage volume to request. Value can be expressed in the same "quantity" format as CPU or memory resources. Examples: "40Gi", "1T"
ephemeralModeSupported boolean	Whether it is allowed to omit persistent storage altogether. Note that regardless of this value, if a persistent storage volume is requested then the minimum size will be enforced. Optional: defaults to false.

Role, Service, and Role/Service Association

These types define the services that the app can provide, and how those services can be deployed in different groupings among the members of a virtual cluster. They are brought together in an app configuration.

Role

Field	Description
id string	Identifier unique among roles within this app definition. Must be non-empty. Pattern: `^(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])?$`
cardinality string	Describes the allowed number of role members. If specified as an integer, that number is both min and max. If specified as an integer with the `+` symbol appended, that number is the min (with no max). Examples: "1", "0+", "2+"
imageRepoTag string	The Docker image to be used for role members. Optional: can be left unspecified if the app resource specifies a defaultImageRepoTag. Examples: "my_dockerhub_repo/my_imagename:my_tag" or "quay.io/my_quay_repo/my_imagename:my_tag"
configPackage null or ConfigPackage	The app setup package to be used for role members (null indicates "no package"). Optional: if unspecified, the app resource's defaultConfigPackage value will be used.
persistDirs string array	The list of filesystem directories to be placed on persistent shared storage for role members (if requested). See defaultPersistDirs for more discussion. Optional: can be left unspecified if the app resource specifies a defaultPersistDirs. Pattern per element: `^/.*[^/]$`
minResources resources object	Any required resource amounts for this role, in the same form used to specify limits or requests in ResourceRequirements. If a minimum value for a kind of resource is specified here, then a KubeDirectorCluster instantiating a virtual cluster for this app must request at least that amount in its relevant role spec.
	properties supported by KD v0.5.0+ below
eventList string array	Specify which KubeDirectorCluster lifecycle events will cause the app setup package's script to be invoked, for members in this role. See defaultEventList for more discussion. May be "configure", "addnodes", or "delnodes", with the possibility of other event types in future releases. Optional: can be left unspecified if the app resource specifies a defaultEventList.
	properties supported by KD v0.6.0+ below
containerSpec ContainerSpec	Miscellaneous properties to set for role member containers. Optional.
	properties supported by KD v0.8.0+ below
minStorage MinPersistentStorageSpec	Minimum size required for the persistent shared storage volume for each role member. Optional. If omitted, the role's members will not require persistent storage and may be given a volume of any size (or no volume at all).
	properties supported by KD v0.9.0+ below
maxLogSizeDump integer	The maximum number of characters to be stored in the startScriptStdoutMessage or startScriptStderrMessage fields of a KubeDirectorCluster MemberStateDetail for a member of this role. Setting this to 0 will disable those fields. Setting this to large values for roles with potentially large numbers of members should be done only for development/debugging purposes and with care, as the overall size of a KubeDirectorCluster resource is finite (this size can differ depending on K8s config but 1 MB is a good rule of thumb). Optional: if unspecified, the app resource's defaultMaxLogSizeDump value will be used.

Service

Field	Description
id string	Identifier unique among services within this app definition. Must be non-empty and less than 16 characters long. Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
label Label	Service name and description. Optional.
endpoint Endpoint	Network location for service access. Must be specified if service is intended for access from outside the virtual cluster. Optional.

RoleServiceAssociation

Field	Description
roleID string	Identifier for a role within this app definition.
serviceIDs string array	Identifiers for services within this app definition that will be present on members of the role.

App Configuration

This type defines a particular set of roles and services that will be in use in a deployed virtual cluster.

Note that future versions of KubeDirectorApp will introduce "config choices" that define different configurations which can be selected at deploy-time. Currently however there is only one configuration.

AppConfig

Field	Description
selectedRoles string array	Identifiers of roles that will be active (deployable) by default. If an identified role has a nonzero minimum number of members, then a spec for that role must be included in the KubeDirectorCluster resource spec at deploy-time. If a role is not identified here, any spec provided for it will be ignored.
roleServices RoleServiceAssociation array	Identifiers of which services will be active on the members of which roles.
configMeta string dictionary	An object with arbitrarily-named string-valued properties. Provides extra information available to the app setup scripts. Optional.

App Resource

The top-level object spec and its k8s metadata.

Properties marked with † will not be present in the KubeDirectorApp resource when it is fetched back from k8s. They can however can be set when creating or editing the resource. They are used to provide defaults for certain per-role properties.

KubeDirectorAppSpec

Field	Description
label Label	Description of the app.
distroID string	Identifier that will remain constant across multiple versions of the same app.
version string	Identifier for this version of the app. Note that this is the version of the KubeDirectorApp form of the app, not necessarily the version of the application software itself.
configSchemaVersion integer	Deprecated. Previously used for managing the schema for config JSON injected into containers for consumption by app setup. No longer used.
defaultImageRepoTag † string	The default Docker image to use when deploying role members. Optional. If omitted, every role must specify its own image. Examples: "my_dockerhub_repo/my_imagename:my_tag" or "quay.io/my_quay_repo/my_imagename:my_tag"
defaultConfigPackage † null or ConfigPackage	The default app setup package to use when deploying role members (null indicates "no package"). Optional: defaults to null.
defaultPersistDirs † string array	The default list of filesystem directories to be placed on persistent shared storage for role members (if requested). These should be the app-required directories; KubeDirector itself may need to mount other directories as well. Optional. Pattern per element: `^/.*[^/]$`
roles Role array	Definitions of roles that make up the app.
services Service array	Definitions of service endpoints that the app can provide.
config AppConfig	The selection of active roles and the associations of services with roles.
capabilities string array	A list of Docker capabilities that will be added to the container SecurityContext for each deployed role member. Optional.
systemdRequired boolean	Whether the app uses systemd to control its services. Optional: defaults to false.
	properties supported by KD v0.5.0+ below
defaultEventList string array	Specify which KD cluster lifecycle events will cause the app setup package's script to be invoked. May be "configure", "addnodes", or "delnodes", with the possibility of other event types in future releases. Specifying the minimal set of relevant events can result in better configuration behavior when cluster members are down, since in some cases attempts to notify those members can be skipped. (For an app with multiple roles, it is likely that this event list will need to be customized per-role using the eventList property there.) Optional: can be left unspecified to request all event notifications.
	properties supported by KD v0.5.2+ below
logoURL string	URL of an image that can be used to represent this app in a listing or catalog. (Note that if the protocol is "file", it is up to the consumer/client to determine the relevant filesystem, so that protocol is only useful in tightly-integrated systems.) Optional. Pattern: `^(file\|https\|http?)://.+\.(jpeg\|png)$`
	properties supported by KD v0.9.0+ below
defaultMaxLogSizeDump † integer	The default maximum number of characters to be stored in the startScriptStdoutMessage or startScriptStderrMessage fields of a KubeDirectorCluster MemberStateDetail. Optional: defaults to 256.