Skip to main content

NitroEnclaveDeployment (v1alpha1) API Reference

NitroEnclaveDeployment is a Kubernetes CustomResourceDefinition (CRD) that defines a deployment of AWS Nitro Enclaves within an OBLV Deploy cluster. It specifies the desired number of enclave instances (replicas) and their configuration (resources, networking, plugins, etc.), and reports status information such as the number of running enclaves.

NitroEnclaveDeployment v1alpha1 k8s

FieldDescription
apiVersionAPIVersion defines the versioned schema of this object. Servers should convert recognized schemas to the latest internal value and may reject unrecognized values. More info
kindKind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info
metadataStandard object metadata. More info
specSpecification of the desired behavior of the NitroEnclaveDeployment.
statusMost recently observed status of the NitroEnclaveDeployment.

NitroEnclaveDeploymentSpec v1alpha1 k8s

FieldDescription
replicasRequired. The number of enclave pod replicas to run.
serviceNameThe name of the headless Service governing the pods of the underlying StatefulSet.
podLabelsKey-value pairs to label each enclave pod (applied to pod metadata).
ingressConfiguration for network ingress to the enclaves. If not specified, ingress is disabled by default.
enclaveCpuCountRequired. The number of vCPUs to allocate to each enclave. Must be at least 1.
hugepages-1GiThe amount of 1 GiB hugepages to allocate to the enclave (e.g., "1Gi"). One of hugepages-1Gi or hugepages-2Mi must be provided.
hugepages-2MiThe amount of 2 MiB hugepages to allocate to the enclave (e.g., "512Mi"). One of hugepages-1Gi or hugepages-2Mi must be provided.
serviceAccountService account name to use for the enclave pods (for access to Kubernetes API or other resources).
caCertDetailsRequired. The CA certificate details to use inside the enclave for establishing trust.
userPluginsRequired. A list of user-provided plugin containers to run inside each enclave. Must include at least one plugin.
pluginsConfiguration for the privileged built-in plugins (Auth, Logging, Telemetry).

NitroEnclaveDeploymentStatus v1alpha1 k8s

FieldDescription
deploymentNameThe name of the underlying Kubernetes StatefulSet that is running the enclave pods.
statusOverall status of the NitroEnclaveDeployment (e.g., "Scheduled", "Error").
replicasThe number of enclave pod replicas currently running.
selectorThe label selector used to identify the enclave pods.
readyReplicasThe number of enclave pod replicas that are in Ready state.
availableReplicasThe number of enclave pod replicas considered available.
readyReplicasRatioThe ratio of ready replicas to total replicas (e.g., "3/5").

Ingress v1alpha1 k8s

The ingress field configures an optional network ingress (AWS Network Load Balancer) for reaching the enclave pods.

FieldDescription
enabledRequired. Whether to enable an ingress for this NitroEnclaveDeployment.
internetFacingWhether the ingress load balancer should be internet-facing (external) or internal to the VPC. Required if enabled is true.
dnsHostNameThe DNS host name to use for the ingress load balancer. Required if enabled is true.
ingressTlsCertificateName of the Kubernetes Secret containing the TLS certificate to use at the ingress (the certificate must be in PEM format). Required if enabled is true.
portsList of port mappings for the ingress. Each mapping defines a load balancer port and target port. At least one port must be specified if ingress is enabled.
ingressSecurityGroups(Optional) A list of AWS security group IDs to attach to the ingress load balancer.

Each entry in ports is a port mapping for the ingress:

  • port: Port number on the load balancer (NLB) to expose (1-65535).
  • targetPort: Port on the enclave pod to forward traffic to (1-65535).

CaCertDetails v1alpha1 k8s

CaCertDetails provides the configuration for injecting a Certificate Authority (or other certificate material) into the enclave. This is used to establish a trusted certificate inside the enclave for TLS communications.

FieldDescription
enclaveCertTypeThe mode of certificate provisioning for the enclave. Supported values: CA_PROVIDED, ENCLAVE_GENERATED, LEAF_CERT_PROVIDED, ACME. This setting determines how the enclave gets its TLS certificate: for example, CA_PROVIDED means you supply a CA certificate and key, ENCLAVE_GENERATED means the enclave will generate its own certificate, LEAF_CERT_PROVIDED means you supply an existing leaf certificate and key, and ACME means the certificate will be obtained via ACME (Let's Encrypt). Required.
bucketThe S3 bucket name where certificate material is stored (used for CA_PROVIDED or LEAF_CERT_PROVIDED types).
caCertS3KeyThe S3 object key (path) for the certificate file in the bucket. For CA_PROVIDED, this should be the CA certificate. For LEAF_CERT_PROVIDED, this is the leaf certificate.
caEncryptedS3KeyThe S3 object key for the encrypted private key file corresponding to the certificate. For CA_PROVIDED, this is the CA’s private key (encrypted). For LEAF_CERT_PROVIDED, this is the leaf certificate’s private key (encrypted).
awsRegionAWS region where the S3 bucket (and KMS key) reside.
kmsKeyIdThe ID of the AWS KMS key used to encrypt the private key file in S3.
encryptionAlgorithmThe algorithm used for encrypting the private key (for example, AES-256).
acmeCertDomainNameThe domain name for which to obtain a certificate via ACME (Let's Encrypt).
acmeContactEmailThe contact email used for ACME registration (Let’s Encrypt account email).
acmeServerUrlThe URL of the ACME server to use for certificate issuance.
acmeRootCaThe root CA certificate for the ACME server. This is retrieved from a ConfigMap.
subjectAltNamesA list of additional Subject Alternative Names (DNS names) to include in the certificate.

For acmeRootCa reference:

  • configMapKeyRef – Specifies a key from a ConfigMap to retrieve the root CA certificate. Provide the ConfigMap name and the desired key containing the certificate in PEM format.

Note:

  • For enclaveCertType = ACME, you must provide acmeCertDomainName, acmeContactEmail, and subjectAltNames.
  • For enclaveCertType = CA_PROVIDED or LEAF_CERT_PROVIDED, ensure that you have provided bucket, caCertS3Key, caEncryptedS3Key, awsRegion, and kmsKeyId pointing to the certificate and key stored in S3.

UserPlugin v1alpha1 k8s

The userPlugins field is a list of user-provided plugin container configurations. Each entry defines one container that will run inside the enclave alongside the built-in plugins.

FieldDescription
nameRequired. Name of the user plugin (unique identifier).
imageRequired. Container image for the user plugin.
imagePullSecretName of a Secret for pulling the image from a private registry (if needed).
hostNetworkWhether the plugin's pod should use the host's network namespace. Defaults to false.
portsPort mappings for this container (hostPort to containerPort).
volumesList of volumes to mount into the container.
envList of environment variables to set in the container.
outboundConnectionsList of allowed outbound connections from this container.
commandOverride default container entrypoint with this command (if provided). More info.
argsArguments to pass to the container entrypoint/command. More info.
securityContextSecurity settings for the container

Ports: If ports are specified, each item should include:

  • hostPort: Port number on the host to expose (1025-65535). Optional; if not provided, the port will not be accessible from the host network.
  • containerPort: Port number inside the container to expose (1-65535). Required for each port mapping.

PrivilegedPlugin v1alpha1 k8s

The plugins field configures the privileged plugins that run alongside user plugins within the enclave. Three plugins are available:

  • auth: Authentication and authorization service.
  • logging: Log streaming service (for enclave logs).
  • telemetry: Telemetry and metrics collection service.

Each plugin can be configured and structure for each plugin is similar to a user plugin, with some differences as noted below.

FieldDescription
authConfiguration of the auth plugin.
loggingConfiguration of the logging plugin.
telemetryConfiguration of the telemetry plugin.

AuthPlugin v1alpha1 k8s

The auth plugin provides authentication and authorization within the enclave.

FieldDescription
nameRequired. Name of the auth plugin container.
imageRequired. Container image for the auth plugin.
imagePullSecretSecret name for pulling the auth plugin image, if required.
portsPort mappings for the auth plugin container (hostPort to containerPort).
volumesList of volumes to mount into the auth container.
envList of environment variables to set in the auth container.
outboundConnectionsList of allowed outbound connections from the auth container.
commandCommand to override the container's entrypoint for the auth plugin (if needed). More info.
argsArguments for the auth plugin command. More info.
securityContextSecurity settings for the auth container
resourcesResource limits for the auth plugin container

Ports: Same structure as described above for userPlugins.

LoggingPlugin v1alpha1 k8s

The logging plugin forwards enclave logs.

FieldDescription
nameRequired. Name of the logging plugin container.
imageRequired. Container image for the logging plugin.
imagePullSecretSecret name for pulling the logging plugin image, if required.
volumesList of volumes to mount into the logging container.
envList of environment variables to set in the logging container.
outboundConnectionsList of allowed outbound connections from the logging container.
commandCommand to override the container's entrypoint for the logging plugin. More info.
argsArguments for the logging plugin command. More info.
securityContextSecurity settings for the logging container

TelemetryPlugin v1alpha1 k8s

The telemetry plugin collects metrics and telemetry data.

FieldDescription
nameRequired. Name of the telemetry plugin container.
imageRequired. Container image for the telemetry plugin.
imagePullSecretSecret name for pulling the telemetry plugin image, if required.
portsPort mappings for the telemetry plugin container (hostPort to containerPort).
volumesList of volumes to mount into the telemetry container.
envList of environment variables to set in the telemetry container.
outboundConnectionsList of allowed outbound connections from the telemetry container.
commandCommand to override the container's entrypoint for the telemetry plugin.
argsArguments for the telemetry plugin command.
securityContextSecurity settings for the telemetry container

Ports: Same structure as described above for userPlugins.

Volume v1alpha1 k8s

A Volume describes a volume that can be mounted into a container. It may reference a host path or a ConfigMap.

FieldDescription
nameRequired. Name of the volume (must be unique within the container).
containerPathRequired. Path inside the container where the volume will be mounted.
readOnlyRequired. Whether the volume mount is read-only (true or false).
sourceRequired. The source of the volume content. Exactly one of the following must be specified: a host path on the node, or a ConfigMap reference.

The source field is an object that must include either:

  • hostPath – Path on the host filesystem to mount into the enclave (e.g., /mnt/data).
  • configMap – Reference to a ConfigMap to mount. The ConfigMap reference has:
    • name – Name of the ConfigMap.
    • items – A list of key/path pairs specifying which entries in the ConfigMap to project into the volume. Each item has a key (the ConfigMap key) and path (the file path under the mount where that value will be written).

Note: You must specify either hostPath or configMap in a Volume's source, but not both.

EnvVar v1alpha1 k8s

An EnvVar represents an environment variable to set in a container.

FieldDescription
nameRequired. Name of the environment variable.
valueThe literal value of the environment variable. Mutually exclusive with valueFrom.
valueFromSource for the environment variable's value. Mutually exclusive with value.

If valueFrom is used, it should reference exactly one of:

  • configMapKeyRef – Selects a key from a ConfigMap. Provide the ConfigMap name and the desired key. Optionally, set optional: true to ignore this env var if the ConfigMap or key is missing.
  • secretKeyRef – Selects a key from a Secret. Provide the Secret name and key. Optionally, set optional: true to ignore this env var if the Secret or key is missing.
  • fieldRef – Selects a field of the pod (such as metadata.name or status.podIP). Provide the fieldPath to specify which field to use.

OutboundConnection v1alpha1 k8s

OutboundConnection defines an allowed outgoing network connection from an enclave container.

FieldDescription
typeThe type of outbound connection. One of "default", "enclave", or "proxy". Defaults to "default".
  • default: Standard TCP/UDP egress.
  • enclave: Enclave-to-enclave secure connection.
  • proxy: Egress via an attestation proxy service.
fqdnFully Qualified Domain Name of the destination host. Required.
portDestination port number (1-65535). Required.
proxyUrlURL of the attestation proxy (for proxy type connections). Required if type = "proxy".
attestationPortPort on the proxy to use for attestation (for proxy type). Required if type = "proxy".
attestationIntervalSecondsInterval (in seconds) for periodic attestation. Must be between 60 and 3600. Default is 300. For enclave and proxy types, this defines how frequently attestation is performed.
configMapName of a ConfigMap containing configuration for peer enclave connections (used only for enclave type). Required if type = "enclave".

SecurityContext v1alpha1 k8s

SecurityContext sets security options for a container (either a user plugin or a built-in plugin). These fields correspond to Kubernetes container securityContext settings.

FieldDescription
allowPrivilegeEscalationAllow processes in the container to gain privileges via setuid/setgid binaries. Defaults to true if not set.
capabilitiesLinux capabilities to add or drop from the container. This is an object with two optional lists: add and drop, each listing capability names.
privilegedRun the container in privileged mode (with full host privileges).
readOnlyRootFilesystemMount the container's root filesystem as read-only.
runAsUserThe Unix user ID to run the container process as.
runAsGroupThe Unix group ID to run the container process as.
runAsNonRootRequire that the container runs as a non-root user. If true, the container will not start if run as UID 0 (root).
seLinuxOptionsSELinux label to apply to the container, given as an object with fields user, role, type, and level.
seccompProfileSeccomp filtering profile for the container, provided as an object with fields:
  • type: Seccomp profile type (e.g., "RuntimeDefault", "Localhost", "Unconfined"; required).
  • localhostProfile: Path to a pre-installed seccomp profile (required if type is "Localhost").