Skip to content

Latest commit

 

History

History
711 lines (631 loc) · 26.2 KB

appv1.md

File metadata and controls

711 lines (631 loc) · 26.2 KB
Raw

kVDI CRD Reference

Packages:

Types

app.kvdi.io/v1

Package v1 contains API Schema definitions for the App v1 API group

Resource Types:

AppConfig

(Appears on: VDIClusterSpec)

AppConfig represents app configurations for the VDI cluster

Field Description
image string

The image to use for the app instances. Defaults to the public image matching the version of the currently running manager.
corsEnabled bool

Whether to add CORS headers to API requests
auditLog bool

Whether to log auditing events to stdout
replicas int32

The number of app replicas to run
serviceType Kubernetes core/v1.ServiceType

The type of service to create in front of the app instance. Defaults to LoadBalancer.
serviceAnnotations map[string]string

Extra annotations to apply to the app service.
tls TLSConfig

TLS configurations for the app instance
resources Kubernetes core/v1.ResourceRequirements

Resource requirements to place on the app pods

AuthConfig

(Appears on: VDIClusterSpec)

AuthConfig will be for authentication driver configurations. The goal is to support multiple backends, e.g. local, oauth, ldap, etc.

Field Description
allowAnonymous bool

Allow anonymous users to create desktop instances
adminSecret string

A secret where a generated admin password will be stored
tokenDuration string

How long issued access tokens should be valid for. When using OIDC auth you may want to set this to a higher value (e.g. 8-10h) since the refresh token flow will not be able to lookup a user’s grants from the provider. Defaults to 15m.
defaultRoleRules []rbacv1.Rule

The rules to apply to the default role created for this cluster. These are the rules applied to anonymous users (if allowed) and non-grouped OIDC users. They can also be used for convenience when getting started. The defaults only allow for launching templates in the appNamespace.
localAuth LocalAuthConfig

Use local auth (secret-backed) authentication
ldapAuth LDAPConfig

Use LDAP for authentication.
oidcAuth OIDCConfig

Use OIDC for authentication

DesktopsConfig

(Appears on: VDIClusterSpec)

DesktopsConfig represents global configurations for desktop sessions.

Field Description
maxSessionLength string

When configured, desktop sessions will be forcefully terminated when the time limit is reached.
sessionsPerUser int

The maximum number of sessions a user can run at a time. A zero value (or undefined) means no limit. When using a userdataSpec, you might want to set this value to 1 if you aren’t using ReadWriteMany volumes. The storage controller would inevitably enforce this behavior anyway, but you would save the kvdi-manager some extra work.

GrafanaConfig

(Appears on: MetricsConfig)

GrafanaConfig contains configuration options for the grafana sidecar.

Field Description
enabled bool

Set to true to run a grafana sidecar with the app pods. This can be used to visualize data in the prometheus deployment.

K8SSecretConfig

(Appears on: SecretsConfig)

K8SSecretConfig uses a Kubernetes secret to store and retrieve sensitive values.

Field Description
secretName string

The name of the secret backing the values. Default is <cluster-name>-app-secrets.

LDAPConfig

(Appears on: AuthConfig)

LDAPConfig represents the configurations for using LDAP as the authentication backend.

Field Description
url string

The URL to the LDAP server.
tlsInsecureSkipVerify bool

Set to true to skip TLS verification of an ldaps connection.
tlsCACert string

The base64 encoded CA certificate to use when verifying the TLS certificate of the LDAP server.
bindUserDNSecretKey string

If you want to use the built-in secrets backend (vault or k8s currently), set this to either the name of the secret in the vault path (the key must be “data” for now), or the key of the secret used in secrets.k8sSecret.secretName. In default configurations this is kvdi-app-secrets. Defaults to ldap-userdn.
bindPasswordSecretKey string

Similar to the bindUserDNSecretKey, but for the location of the password secret. Defaults to ldap-password.
bindCredentialsSecret string

If you’d rather create a separate k8s secret (instead of the configured backend) for the LDAP credentials, set its name here. The keys in the secret need to be defined in the other fields still. Default is to use the secret backend.
adminGroups []string

Group DNs that are allowed administrator access to the cluster. Kubernetes admins will still have the ability to change configurations via the CRDs.
userSearchBase string

The base scope to search for users in. Default is to search the entire directory.
userIDAttribute string

The user ID attribute to use when looking up a provided username. Defaults to uid. This value may be different depending on the LDAP provider. For example, in an Active Directory environment you may want to set this value to sAMAccountName.
userGroupsAttribute string

The user attribute use to lookup group membership in LDAP. Defaults to memberOf.
userStatusAttribute string

The user attribute to use when querying if an account is active. Defaults to accountStatus. Only takes effect if doStatusCheck is true. A user is considered disabled when the attribute is both present and matches the value in userStatusDisabledValue.
userStatusDisabledValue string

The value for the userStatusAttribute that signifies that the user is disabled. Defaults to inactive.
doStatusCheck bool

When set to true, the authentication provider will query the user’s attributes for the userStatusAttribute and make sure it matches the value in userStatusEnabledValue before attemtping to bind.

LocalAuthConfig

(Appears on: AuthConfig)

LocalAuthConfig represents a local, ‘passwd’-like authentication driver.

MetricsConfig

(Appears on: VDIClusterSpec)

MetricsConfig contains configuration options for gathering metrics.

Field Description
serviceMonitor ServiceMonitorConfig

Configurations for creating a ServiceMonitor CR for a pre-existing prometheus-operator installation.
prometheus PrometheusConfig

Prometheus deployment configurations.g.
grafana GrafanaConfig

Grafana sidecar configurations.

OIDCConfig

(Appears on: AuthConfig)

OIDCConfig represents configurations for using an OIDC/OAuth provider for authentication.

Field Description
issuerURL string

The OIDC issuer URL used for discovery
clientIDKey string

When using the built-in secrets backend, the key to where the client-id is stored. Set this to either the name of the secret in the vault path (the key must be “data” for now), or the key of the secret used in secrets.k8sSecret.secretName. When configuring clientCredentialsSecret, set this to the key in that secret. Defaults to oidc-clientid.
clientSecretKey string

Similar to clientIDKey, but for the location of the client secret. Defaults to oidc-clientsecret.
clientCredentialsSecret string

When creating your own kubernets secret with the clientIDKey and clientSecretKey, set this to the name of the created secret. It must be in the same namespace as the manager and app instances. Defaults to oidc-clientsecret.
redirectURL string

The redirect URL path configured in the OIDC provider. This should be the full path where kvdi is hosted followed by /api/login. For example, if kvdi is hosted at https://kvdi.local, then this value should be set https://kvdi.local/api/login.
scopes []string

The scopes to request with the authentication request. Defaults to ["openid", "email", "profile", "groups"].
groupScope string

If your OIDC provider does not return a groups object, set this to the user attribute to use for binding authenticated users to VDIRoles. Defaults to groups.
adminGroups []string

Groups that are allowed administrator access to the cluster. Kubernetes admins will still have the ability to change rbac configurations via the CRDs.
tlsInsecureSkipVerify bool

Set to true to skip TLS verification of an OIDC provider.
tlsCACert string

The base64 encoded CA certificate to use when verifying the TLS certificate of the OIDC provider.
allowNonGroupedReadOnly bool

Set to true if the OIDC provider does not support the “groups” claim (or any valid alternative) and/or you would like to allow any authenticated user read-only access.
preserveTokens bool

The access tokens returned by the OIDC provider are usually discarded after identify information is retrieved from them. If you set this to true, these fields will be available for mapping in desktops at the following paths:

  • {{ .Session.Data.access_token }}
  • {{ .Session.Data.token_type }}
  • {{ .Session.Data.refresh_token }}
  • {{ .Session.Data.expiry }}

NOTE: This should be considered an insecure option and only turned on taking into account the inherent risks. If the access token used for authorizing actions against the kvdi API gets compromised, it would be relatively easy for the attacker to extract this information from the token and use it for authenticating against third-party resources. Additionally, when mapping these values to desktops, they will be stored temporarily in Kubernetes Secrets. The security of those secrets depends highly on your Kubernetes RBAC setup and who has access to secrets in the namespace where the Desktop is. So in short, it would be wise to only use this setting in trusted environments where access to the necessary kubernetes APIs is only available to a select group of administrators, and the risk of the user using a compromised browser is minimal.

PrometheusConfig

(Appears on: MetricsConfig)

PrometheusConfig contains configuration options for a prometheus deployment.

Field Description
create bool

Set to true to create a prometheus instance.
resources Kubernetes core/v1.ResourceRequirements

Resource requirements to place on the Prometheus deployment

SecretsConfig

(Appears on: VDIClusterSpec)

SecretsConfig configurese the backend for secrets management.

Field Description
k8sSecret K8SSecretConfig

Use a kubernetes secret for storing sensitive values. If no other coniguration is provided then this is the fallback.
vault VaultConfig

Use vault for storing sensitive values. Requires kubernetes service account authentication.

ServiceMonitorConfig

(Appears on: MetricsConfig)

ServiceMonitorConfig contains configuration options for creating a ServiceMonitor.

Field Description
create bool

Set to true to create a ServiceMonitor object for the kvdi metrics.
labels map[string]string

Extra labels to apply to the ServiceMonitor object. Set these to the selector in your prometheus-operator configuration (usually {"release": "<helm_release_name>"}). Defaults to {"release": "prometheus"}.

TLSConfig

(Appears on: AppConfig)

TLSConfig contains TLS configurations for kVDI.

Field Description
serverSecret string

A pre-existing TLS secret to use for the HTTPS listener. If not defined, a certificate is generated.

UserdataSelector

(Appears on: VDIClusterSpec)

UserdataSelector represents a means for selecting pre-existing userdata PVCs based off a label or name match. Note that you will need to restrict templates to launching in namespaces that contain the PVCs yourself.

Field Description
matchName string

MatchName is a pattern to match for the name of the PVC. The string ${USERNAME} will be replaced in the pattern with the actual username when searching for the volume. Note, this will only work if usernames are DNS compliant.
matchLabel string

MatchLabel is a label key to use to select a PVC for the user. The value will in the selector will be the name of the user launching the session. Use this if your usernames may not always be DNS compliant.

UserdataSpec

(Appears on: VDIClusterSpec)

UserdataSpec is an inline of the corev1 PersistentVolumeClaimSpec. It contains additional fields for controlling how kvdi works with volumes.

Field Description
PersistentVolumeClaimSpec Kubernetes core/v1.PersistentVolumeClaimSpec

(Members of PersistentVolumeClaimSpec are embedded into this type.)
retainPVCs bool

RetainPVCs tells the desktop controller to leave PVCs in-tact after they are allocated for a user. The default behavior is to free the volume from the PVC after each desktop session so it can be used across other namespaces. Note that if you set this value to true users will only be able to launch sessions in a single namespace (unless the PVC is manually removed).

VDICluster

VDICluster is the Schema for the vdiclusters API

Field Description
metadata Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field.
spec VDIClusterSpec

appNamespace string

The namespace to provision application resurces in. Defaults to the default namespace
imagePullSecrets []Kubernetes core/v1.LocalObjectReference

Pull secrets to use when pulling container images
userdataSpec UserdataSpec

The configuration for user $HOME volumes to be managed by kVDI.

NOTE: Even though the controller will try to force the reclaim policy on created volumes to Retain, you may want to set it explicitly on your storage-class controller as an extra safeguard.
userdataSelector UserdataSelector

A configuration for selecting pre-existing PVCs to use as the $HOME directory for sessions. This configuration takes precedence over userdataSpec.
app AppConfig

App configurations.
auth AuthConfig

Authentication configurations
desktops DesktopsConfig

Global desktop configurations
secrets SecretsConfig

Secrets backend configurations
metrics MetricsConfig

Metrics configurations.
status VDIClusterStatus

VDIClusterSpec

(Appears on: VDICluster)

VDIClusterSpec defines the desired state of VDICluster

Field Description
appNamespace string

The namespace to provision application resurces in. Defaults to the default namespace
imagePullSecrets []Kubernetes core/v1.LocalObjectReference

Pull secrets to use when pulling container images
userdataSpec UserdataSpec

The configuration for user $HOME volumes to be managed by kVDI.

NOTE: Even though the controller will try to force the reclaim policy on created volumes to Retain, you may want to set it explicitly on your storage-class controller as an extra safeguard.
userdataSelector UserdataSelector

A configuration for selecting pre-existing PVCs to use as the $HOME directory for sessions. This configuration takes precedence over userdataSpec.
app AppConfig

App configurations.
auth AuthConfig

Authentication configurations
desktops DesktopsConfig

Global desktop configurations
secrets SecretsConfig

Secrets backend configurations
metrics MetricsConfig

Metrics configurations.

VaultConfig

(Appears on: SecretsConfig)

VaultConfig represents the configurations for connecting to a vault server.

Field Description
address string

The full URL to the vault server. Same as the VAULT_ADDR variable.
caCertBase64 string

The base64 encoded CA certificate for verifying the vault server certificate.
insecure bool

Set to true to disable TLS verification.
tlsServerName string

Optionally set the SNI when connecting using HTTPS.
authRole string

The auth role to assume when authenticating against vault. Defaults to kvdi.
secretsPath string

The base path to store secrets in vault. “Keys” for other configurations in the context of the vault backend can be put at <secretsPath>/<secretKey>.data. This will change in the future to support keys inside the secret itself, instead of assuming data.

Generated with gen-crd-api-reference-docs on git commit c911719.