Connector
A connector configures a platform integration, such as a shared database, Argo CD, or observability. Connectors are cluster-scoped. Callers who can update a connector see its full spec. All other callers, including connector viewers and tenants, see a redacted view without credentials or connection details. Tenants see only the connectors assigned to them and cannot change them. Watch isn't supported.
Connector example​
An example Connector:
apiVersion: management.loft.sh/v1
kind: Connector
metadata:
name: shared-postgres
spec:
displayName: Shared PostgreSQL
sharedDatabase:
dialect: postgres
endpoint: postgres.example.com
password: replace-with-database-password
port: "5432"
user: platform
status: {}
Connector reference​
kind string ​
Kind 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: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
kind string ​apiVersion string ​
APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
apiVersion string ​metadata object ​
metadata object ​name string ​
Name must be unique within a namespace. Is required when creating resources, although
some resources may allow a client to request the generation of an appropriate name
automatically. Name is primarily intended for creation idempotence and configuration
definition.
Cannot be updated.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names#names
name string ​generateName string ​
GenerateName is an optional prefix, used by the server, to generate a unique
name ONLY IF the Name field has not been provided.
If this field is used, the name returned to the client will be different
than the name passed. This value will also be combined with a unique suffix.
The provided value has the same validation rules as the Name field,
and may be truncated by the length of the suffix required to make the value
unique on the server.
If this field is specified and the generated name exists, the server will return a 409.
Applied only if Name is not specified.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#idempotency
generateName string ​namespace string ​
Namespace defines the space within which 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: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces
namespace string ​selfLink string ​
Deprecated: selfLink is a legacy read-only field that is no longer populated by the system.
selfLink string ​uid string ​
UID is the unique in time and space value for this object. It is typically generated by
the server on successful creation of a resource and is not allowed to change on PUT
operations.
Populated by the system.
Read-only.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names#uids
uid string ​resourceVersion string ​
An opaque value that represents the internal version of this object that can
be used by clients to determine when objects have changed. May be used for optimistic
concurrency, change detection, and the watch operation on a resource or set of resources.
Clients must treat these values as opaque and passed unmodified back to the server.
They may only be valid for a particular resource or set of resources.
Populated by the system.
Read-only.
Value must be treated as opaque by clients and .
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#concurrency-control-and-consistency
resourceVersion string ​generation integer ​
A sequence number representing a specific generation of the desired state.
Populated by the system. Read-only.
generation integer ​creationTimestamp object ​
CreationTimestamp is a timestamp representing the server time when this object was
created. It is not guaranteed to be set in happens-before order across separate operations.
Clients may not set this value. It is represented in RFC3339 form and is in UTC.
Populated by the system.
Read-only.
Null for lists.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
creationTimestamp object ​deletionTimestamp object ​
DeletionTimestamp is RFC 3339 date and time at which this resource will be deleted. This
field is set by the server when a graceful deletion is requested by the user, and is not
directly settable by a client. The resource is expected to be deleted (no longer visible
from resource lists, and not reachable by name) after the time in this field, once the
finalizers list is empty. As long as the finalizers list contains items, deletion is blocked.
Once the deletionTimestamp is set, this value may not be unset or be set further into the
future, although it may be shortened or the resource may be deleted prior to this time.
For example, a user may request that a pod is deleted in 30 seconds. The Kubelet will react
by sending a graceful termination signal to the containers in the pod. After that 30 seconds,
the Kubelet will send a hard termination signal (SIGKILL) to the container and after cleanup,
remove the pod from the API. In the presence of network partitions, this object may still
exist after this timestamp, until an administrator or automated process can determine the
resource is fully terminated.
If not set, graceful deletion of the object has not been requested.
Populated by the system when a graceful deletion is requested.
Read-only.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
deletionTimestamp object ​deletionGracePeriodSeconds integer ​
Number of seconds allowed for this object to gracefully terminate before
it will be removed from the system. Only set when deletionTimestamp is also set.
May only be shortened.
Read-only.
deletionGracePeriodSeconds integer ​labels object ​
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.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels
labels object ​annotations object ​
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.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations
annotations object ​ownerReferences object[] ​
List of objects depended by this object. If ALL objects in the list have
been deleted, this object will be garbage collected. If this object is managed by a controller,
then an entry in this list will point to this controller, with the controller field set to true.
There cannot be more than one managing controller.
ownerReferences object[] ​apiVersion required string ​
API version of the referent.
apiVersion required string ​kind required string ​
Kind of the referent.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
kind required string ​name required string ​
Name of the referent.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names#names
name required string ​uid required string ​
UID of the referent.
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names#uids
uid required string ​controller boolean ​
If true, this reference points to the managing controller.
controller boolean ​blockOwnerDeletion boolean ​
If true, AND if the owner has the "foregroundDeletion" finalizer, then
the owner cannot be deleted from the key-value store until this
reference is removed.
See https://kubernetes.io/docs/concepts/architecture/garbage-collection/#foreground-deletion
for how the garbage collector interacts with this field and enforces the foreground deletion.
Defaults to false.
To set this field, a user needs "delete" permission of the owner,
otherwise 422 (Unprocessable Entity) will be returned.
blockOwnerDeletion boolean ​finalizers string[] ​
Must be empty before the object is deleted from the registry. Each entry
is an identifier for the responsible component that will remove the entry
from the list. If the deletionTimestamp of the object is non-nil, entries
in this list can only be removed.
Finalizers may be processed and removed in any order. Order is NOT enforced
because it introduces significant risk of stuck finalizers.
finalizers is a shared field, any actor with permission can reorder it.
If the finalizer list is processed in order, then this can lead to a situation
in which the component responsible for the first finalizer in the list is
waiting for a signal (field value, external system, or other) produced by a
component responsible for a finalizer later in the list, resulting in a deadlock.
Without enforced ordering finalizers are free to order amongst themselves and
are not vulnerable to ordering changes in the list.
finalizers string[] ​managedFields object[] ​
ManagedFields maps workflow-id and version to the set of fields
that are managed by that workflow. This is mostly for internal
housekeeping, and users typically shouldn't need to set or
understand this field. A workflow can be the user's name, a
controller's name, or the name of a specific apply path like
"ci-cd". The set of fields is always in the version that the
workflow used when modifying the object.
managedFields object[] ​manager string ​
Manager is an identifier of the workflow managing these fields.
manager string ​operation string ​
Operation is the type of operation which lead to this ManagedFieldsEntry being created.
The only valid values for this field are 'Apply' and 'Update'.
operation string ​apiVersion string ​
APIVersion defines the version of this resource that this field set
applies to. The format is "group/version" just like the top-level
APIVersion field. It is necessary to track the version of a field
set because it cannot be automatically converted.
apiVersion string ​time object ​
Time is the timestamp of when the ManagedFields entry was added. The
timestamp will also be updated if a field is added, the manager
changes any of the owned fields value or removes a field. The
timestamp does not update when a field is removed from the entry
because another manager took it over.
time object ​fieldsType string ​
FieldsType is the discriminator for the different fields format and version.
There is currently only one possible value: "FieldsV1"
fieldsType string ​fieldsV1 object ​
FieldsV1 holds the first JSON version format as described in the "FieldsV1" type.
fieldsV1 object ​subresource string ​
Subresource is the name of the subresource used to update that object, or
empty string if the object was updated through the main resource. The
value of this field is used to distinguish between managers, even if they
share the same name. For example, a status update will be distinct from a
regular update using the same manager name.
Note that the APIVersion field is not related to the Subresource field and
it always corresponds to the version of the main resource.
subresource string ​spec object ​
spec object ​displayName string ​
DisplayName is the human-readable name shown in the UI. It is projected from
and stamped to the loft.sh/display-name annotation on the backing Secret.
displayName string ​description string ​
Description is the free-text description shown in the UI. It is projected from
and stamped to the loft.sh/description annotation on the backing Secret.
description string ​sharedDatabase object ​
SharedDatabase is the shared-database connector payload. Exactly one payload
section must be set. Its fields
mirror the Data keys of the backing Secret one to one, so a connector written
through this API is byte-compatible with one written by the UI directly.
sharedDatabase object ​dialect required string ​
Dialect is the database server dialect, mysql or postgres. Data key "type"
(distinct from the connector type label). Required on every write: there
is no server-side default and unknown values are rejected. Reads of a
pre-existing Secret without the key still project mysql, matching how the read
consumers treat such Secrets.
dialect required string ​endpoint required string ​
Endpoint is the host of the database server. Data key "endpoint". Required.
endpoint required string ​port string ​
Port is the port of the database server, kept as a string exactly as stored in
the Data key "port". An empty port defaults by dialect on CREATE ONLY: 5432
for postgres, 3306 for mysql (the same defaults the UI applies). Updates never
default it. For postgres an empty port on update removes the key and the driver
falls back to 5432; for mysql an empty port is rejected on update, because the
mysql driver has no fallback and would dial port 0. A stored mysql connector
without a port is therefore rejected on every update, whatever else the update
changes, until the port is set; such a connector cannot connect until then
anyway, and its Configured condition says so.
port string ​user required string ​
User is the database user the platform connects as. Data key "user". Required.
user required string ​password string ​
Password is the password of the database user. Data key "password". Required
on create unless identityProvider is set. It is a credential: served only to a
caller who could update this connector and absent for every other caller (see
the Connector type). On update an empty password keeps the stored one, so a
read without the credential written back never clears it; switching to
identityProvider removes it. Switching back from identityProvider to password
authentication requires a non-empty password in the request: the stored one
was removed by the earlier switch, so there is nothing to keep.
password string ​identityProvider string ​
IdentityProvider selects password-less IAM authentication. Data key
"identityProvider". The only supported value is "aws"; other values are
rejected. When set, password must be empty and the stored password key is
removed, matching the UI behavior.
identityProvider string ​awsPermissionBoundaryPolicyArn string ​
AWSPermissionBoundaryPolicyARN is the ARN of the IAM policy attached as the
permissions boundary of every IAM role the platform provisions for a tenant
cluster through this connector. It is only read when identityProvider is set.
Unlike the other fields it maps to an annotation on the backing Secret
(connector.platform.vcluster.com/aws-permission-boundary-policy-arn), not to a
Data key, and this field is the one way to write it: the annotation is
projected, so a metadata write carrying a different value is refused. Empty
means no boundary, which is a supported configuration, and an empty value on
update removes the annotation, so a read-modify-write that drops the field
clears a boundary that was set.
awsPermissionBoundaryPolicyArn string ​caCert string ​
CACert is the PEM-encoded CA bundle used to verify the database server's TLS
certificate. Data key "caCert".
caCert string ​sslMode string ​
SSLMode is an explicit Postgres sslmode value (disable, allow, prefer, require,
verify-ca or verify-full) overriding the default policy derived from caCert.
Data key "sslMode".
sslMode string ​argoCd object ​
ArgoCD is the argocd connector payload. Exactly one payload section
must be set. Its fields mirror the Data keys of the
backing Secret one to one, so a connector written through this API is
byte-compatible with one written by the UI directly.
argoCd object ​selfHosted object ​
SelfHosted is a self-hosted Argo CD instance reached directly at the server URL.
Must be unset when akuity is set.
selfHosted object ​server required string ​
Server is the URL the Argo CD API server is reachable at; for akuity this is the
Akuity-hosted Argo CD instance URL. Data key "server". Required, must be an
http or https URL.
server required string ​namespace string ​
Namespace is the namespace Argo CD runs in on the destination cluster. Data key
"namespace". An empty namespace is defaulted to "argocd" on create only (the
same default the UI pre-fills and consumers assume for Secrets without the
key); on update an empty namespace removes the key, and reads fall back to the
same default, so the effective namespace consumers use never changes.
namespace string ​token string ​
Token is the Argo CD API token, the default authentication method. Data key
"token". Required on create unless username and password are set. A credential
(see ConnectorArgoCDSpec): an empty token on update keeps the stored one, and
setting username/password removes it (switching the authentication method, like
the UI does). Keeping is only valid while the stored connector holds a usable
credential: a token, or a full username and password pair (half a pair does not
count). A pre-existing Secret holding neither cannot be updated through this
API, even on unrelated fields, until the request supplies a credential; the
escape hatch is editing the backing Secret directly.
token string ​username string ​
Username is the Argo CD username for basic authentication, used together with
password as the alternative to token. Data key "username". Projected in the full view
only when no token is stored, because the consumer authenticates with the token whenever one
is present and a username beside it describes a method the connector does not use.
username string ​password string ​
Password is the Argo CD password for basic authentication. Data key "password".
Required whenever username is set and no stored password exists: on create, and
on an update that switches from token to basic authentication, since setting the
token had removed the stored password. A credential (see ConnectorArgoCDSpec): an
empty password on an update that keeps basic authentication keeps the stored one,
and setting token removes it (switching the authentication method, like the UI
does).
password string ​caData string ​
CAData is the PEM-encoded CA bundle used to verify the Argo CD server's TLS
certificate. Data key "caData".
caData string ​insecure boolean ​
Insecure skips TLS verification when talking to the Argo CD server. Data key
"insecure". Defaults to false and is always stamped explicitly ("true" or
"false"), exactly like the UI writes it.
insecure boolean ​akuity object ​
Akuity is an Argo CD instance managed by the Akuity Platform: cluster
registration goes through Akuity's control plane API. Must be unset when
selfHosted is set.
akuity object ​server required string ​
Server is the URL the Argo CD API server is reachable at; for akuity this is the
Akuity-hosted Argo CD instance URL. Data key "server". Required, must be an
http or https URL.
server required string ​namespace string ​
Namespace is the namespace Argo CD runs in on the destination cluster. Data key
"namespace". An empty namespace is defaulted to "argocd" on create only (the
same default the UI pre-fills and consumers assume for Secrets without the
key); on update an empty namespace removes the key, and reads fall back to the
same default, so the effective namespace consumers use never changes.
namespace string ​token string ​
Token is the Argo CD API token, the default authentication method. Data key
"token". Required on create unless username and password are set. A credential
(see ConnectorArgoCDSpec): an empty token on update keeps the stored one, and
setting username/password removes it (switching the authentication method, like
the UI does). Keeping is only valid while the stored connector holds a usable
credential: a token, or a full username and password pair (half a pair does not
count). A pre-existing Secret holding neither cannot be updated through this
API, even on unrelated fields, until the request supplies a credential; the
escape hatch is editing the backing Secret directly.
token string ​username string ​
Username is the Argo CD username for basic authentication, used together with
password as the alternative to token. Data key "username". Projected in the full view
only when no token is stored, because the consumer authenticates with the token whenever one
is present and a username beside it describes a method the connector does not use.
username string ​password string ​
Password is the Argo CD password for basic authentication. Data key "password".
Required whenever username is set and no stored password exists: on create, and
on an update that switches from token to basic authentication, since setting the
token had removed the stored password. A credential (see ConnectorArgoCDSpec): an
empty password on an update that keeps basic authentication keeps the stored one,
and setting token removes it (switching the authentication method, like the UI
does).
password string ​caData string ​
CAData is the PEM-encoded CA bundle used to verify the Argo CD server's TLS
certificate. Data key "caData".
caData string ​insecure boolean ​
Insecure skips TLS verification when talking to the Argo CD server. Data key
"insecure". Defaults to false and is always stamped explicitly ("true" or
"false"), exactly like the UI writes it.
insecure boolean ​orgId required string ​
OrgID is the Akuity Platform organization ID. Data key "akuityOrgId". Required.
orgId required string ​instanceId required string ​
InstanceID is the Akuity-hosted Argo CD instance ID. Data key "akuityInstanceId".
Required.
instanceId required string ​apiKeyId required string ​
APIKeyID is the Akuity API key ID. Data key "akuityApiKeyId". Required.
apiKeyId required string ​apiKeySecret string ​
APIKeySecret is the Akuity API key secret. Data key "akuityApiKeySecret".
Required whenever no stored value exists: on create, and on an update that
switches from selfHosted to akuity, since the live Secret of a self-hosted
connector carries no Akuity keys. A credential (see ConnectorArgoCDSpec): an
empty value on an update that stays akuity keeps the stored one.
apiKeySecret string ​agentSize string ​
AgentSize is the resource allocation of the Akuity agent, an Akuity size name of
the form CLUSTER_SIZE_(NAME) such as CLUSTER_SIZE_SMALL, CLUSTER_SIZE_MEDIUM or
CLUSTER_SIZE_LARGE; the value is passed to Akuity as given, so any size Akuity
accepts is valid here. Data key "akuityAgentSize". Empty leaves the sizing to
the Akuity side (medium), like the UI.
agentSize string ​repoServerReplicas string ​
RepoServerReplicas is an optional replica count override for the
argocd-repo-server of the Akuity agent, a positive integer kept as a string
exactly as stored in the Data key "akuityRepoServerReplicas".
repoServerReplicas string ​repoServerMemory string ​
RepoServerMemory is an optional memory limit/request override for the
argocd-repo-server of the Akuity agent, written as a number with an optional
decimal part and an optional SI or binary suffix (k, M, G, T, P, E, Ki, Mi, Gi,
Ti, Pi, Ei), for example "512Mi" or "1Gi". This is the shape the UI accepts; it
is narrower than a full Kubernetes quantity, which also allows exponents such as
1e9 and the milli suffix. Data key "akuityRepoServerMemory".
repoServerMemory string ​netBox object ​
NetBox is the netbox connector payload. Exactly one payload section
must be set. Its fields mirror the Data keys of the
backing Secret one to one, so a connector written through this API is
byte-compatible with one written by the UI directly.
netBox object ​url required string ​
URL is the base URL of the NetBox instance, for example https://netbox.example.com.
Data key "url". Required, must be an http or https URL.
url required string ​apiToken string ​
APIToken is the NetBox API token requests are authenticated with. Data key
"apiToken". Required on create. A credential (see the type comment): an empty
value on update keeps the stored token, and a pre-existing Secret without a
stored token cannot be updated through this API until the request supplies one.
The token must be one created in the NetBox UI: NetBox rejects tokens obtained
from its provisioning endpoint.
apiToken string ​insecure boolean ​
Insecure skips TLS certificate verification of the NetBox URL. Data key
"insecure", always stamped as "true" or "false" exactly like the UI writes it; a
missing or unparsable stored value projects as false, which is how the NetBox
client reads it too.
insecure boolean ​imageStore object ​
ImageStore is the os-image-store connector payload. Exactly one payload section
must be set. The fields of its protocol
block mirror the Data keys of the backing Secret one to one, so a connector
written through this API is exactly what the OSImage store loader reads.
imageStore object ​protocol required string ​
Protocol selects the object store implementation and which block below applies.
Required; only s3 is supported. It is not stored on the backing Secret because
every os-image-store Secret currently describes an S3-compatible store.
protocol required string ​s3 object ​
S3 carries the settings of an S3-compatible store. Required when protocol is s3.
s3 object ​endpoint string ​
Endpoint is the object store address, for example https://minio.example.com. Data
key "endpoint". Optional: empty means AWS S3 itself, resolved from the region. When
set it must be an http or https URL.
endpoint string ​bucket required string ​
Bucket is the bucket image objects live in. Data key "bucket". Required.
bucket required string ​region required string ​
Region is the region SigV4 signs for. Data key "region". Required also for stores
that ignore it, because the signature covers it and there is nothing to fall back
to.
region required string ​forcePathStyle boolean ​
ForcePathStyle addresses the bucket as a path (https://endpoint/bucket/key) instead
of a virtual host (https://bucket.endpoint/key), which most self-hosted stores need.
Data key "forcePathStyle", always stamped as "true" or "false"; a missing stored
value projects as false, which is how the store loader reads it too.
forcePathStyle boolean ​accessKey required string ​
AccessKey is the access key ID of the static credentials. Data key "accessKey".
Required. The credentials must be long-lived: a pre-signed URL is only valid as
long as the credentials that signed it, and upload URLs live 24 hours.
accessKey required string ​secretKey string ​
SecretKey is the secret access key of the static credentials. Data key "secretKey".
Required on create. A credential (see the type comment): an empty value on update
keeps the stored key, and a pre-existing Secret without a stored key cannot be
updated through this API until the request supplies one.
secretKey string ​sessionToken string ​
SessionToken is set only for temporary credentials. Data key "sessionToken".
Optional; an empty value on update removes it. A credential (see the type comment).
Pre-signed URLs expire with the session, so this is meant for short-lived use.
sessionToken string ​observability object ​
Observability is the observability connector payload. It is required when type
is observability and must be unset for every other type. Its fields mirror the
Data keys of the backing Secret one to one (fleetDefault excepted, which is
backed by a server-owned label), so a connector written through this API is
byte-compatible with one written by the UI directly.
observability object ​fleetDefault boolean ​
FleetDefault marks this connector as the one backing the platform-wide fleet
metrics Grafana. It is projected from and stamped to the
platform.vcluster.com/fleet-observability-connector label on the backing Secret,
which is the API for it: a metadata write carrying the label with a value that
disagrees with this field is refused. At most one connector may be the fleet
default: a write claiming it while another connector (including a terminating
one) holds it is rejected with a 409 Conflict naming the holder.
The field is tri-state. Unset carries no opinion: on create the connector
claims the label automatically only when no holder exists anywhere (exactly
like the UI's first create), on update it keeps the connector's current holder
state and can never demote it. True claims the label explicitly (or is
rejected naming the holder), false never claims it and releases it when this
connector is the holder. Reads carry the value true when the label is present
and leave the field unset when it is absent, never an explicit false, so a
read-modify-write round trip of a non-holder stays a no-op instead of
becoming a demotion request. An explicit false is accepted and demotes, but is
never echoed back, so declarative tooling that keeps fleetDefault: false in its
manifest sees a permanent diff on that field.
Moving the fleet default to another connector takes two writes: demote the
holder with an explicit false first, then claim with true on the new
connector. A claim while a holder exists is never an implicit steal.
A pre-existing sparse Secret missing the grafanaUrl key cannot be demoted
through this API: write-time validation rejects the whole update until the
field is filled in. The escape hatch is removing the fleet label on the backing
Secret directly.
fleetDefault boolean ​grafanaUrl string ​
GrafanaURL is the URL of the Grafana instance the platform proxies under
/grafana/. Data key "grafanaUrl". Must be an http or https URL; an empty value
defaults on CREATE ONLY to the in-cluster Grafana the platform ships
(https://grafana.(platform namespace).svc.cluster.local). An emptied value on
update is rejected, matching the UI edit form.
grafanaUrl string ​grafanaInsecureSkipVerify boolean ​
GrafanaInsecureSkipVerify skips TLS verification when the platform talks to
Grafana. Data key "grafanaInsecureSkipVerify": true stores "true", false stores
no key. A write replaces the Secret from the request, so a "false" the UI wrote
earlier does not survive an update; every consumer reads an absent key and
"false" the same way.
grafanaInsecureSkipVerify boolean ​fleetObservabilityDashboardUid string ​
FleetObservabilityDashboardUID is the UID of the Grafana dashboard the fleet
observability view embeds. Data key "fleetObservabilityDashboardUid". An empty
value defaults on CREATE ONLY to "vcluster-fleet-observability", the dashboard
the platform provisions. It may be emptied on update: the fleet view then shows
an empty state until a dashboard is named again.
fleetObservabilityDashboardUid string ​metricsBackendOtlpEndpoint string ​
MetricsBackendOtlpEndpoint is the metrics backend's OTLP write endpoint the
observability gateway forwards tenant metrics to. Data key
"metricsBackendOtlpEndpoint". Must be an http or https URL; an empty value
defaults on CREATE ONLY to the in-cluster Prometheus the platform ships
(https://prom-prometheus-server.(platform namespace).svc.cluster.local/api/v1/otlp).
It may be emptied on update: the gateway controller skips the connector until
both metrics backend endpoints are set.
metricsBackendOtlpEndpoint string ​metricsBackendPromQLEndpoint string ​
MetricsBackendPromQLEndpoint is the metrics backend's PromQL query endpoint.
Data key "metricsBackendPromQLEndpoint". Must be an http or https URL; an
empty value defaults on CREATE ONLY to the in-cluster Prometheus the platform
ships (https://prom-prometheus-server.(platform namespace).svc.cluster.local).
It may be emptied on update: the gateway controller skips the connector until
both metrics backend endpoints are set.
metricsBackendPromQLEndpoint string ​metricsBackendCertSecretName string ​
MetricsBackendCertSecretName references the kubernetes.io/tls Secret with the
client certificate the gateway presents to the metrics backend for mTLS. Data
key "metricsBackendCertSecretName". Optional.
metricsBackendCertSecretName string ​metricsBackendInsecureSkipVerify boolean ​
MetricsBackendInsecureSkipVerify disables TLS verification against the metrics
backend on both the OTLP write and PromQL query paths. Data key
"metricsBackendInsecureSkipVerify": true stores "true", false stores no key. A
write replaces the Secret from the request, so a "false" the UI wrote earlier
does not survive an update; every consumer reads an absent key and "false" the
same way.
metricsBackendInsecureSkipVerify boolean ​metricsBackendServerName string ​
MetricsBackendServerName overrides the TLS server name the query proxy expects
on the metrics backend's certificate, for backends fronted by a proxy or an SNI
router. It applies to the PromQL reads only; the OTLP endpoint's certificate must
still match the endpoint hostname. Data key "metricsBackendServerName". Optional;
the UI has no field for it and the gateway documentation describes it.
metricsBackendServerName string ​grafanaCertSecretName string ​
GrafanaCertSecretName references the kubernetes.io/tls Secret Grafana serves;
the /grafana/ proxy trusts its ca.crt. Data key "grafanaCertSecretName".
Optional.
grafanaCertSecretName string ​observabilityGatewayCertSecretName string ​
ObservabilityGatewayCertSecretName references the kubernetes.io/tls Secret the
observability gateway serves on the OTLP write receiver and metrics
query-proxy. Data key "observabilityGatewayCertSecretName". Optional, and the
two cases are different requests rather than set-versus-unset:
Set it to bring your own certificate. The Secret must exist before you name it
here: the platform never modifies and never deletes a certificate Secret it did
not create, but it does not check that a named Secret exists. Whenever a
reconcile finds no Secret under the name (with the default ClusterIP service
type that is the first reconcile after the create), the gateway self-issues a
certificate under that name and owns it from then on, rotating it when its
SANs change and deleting it with the connector. The name is reported in status
either way; nothing there says who created the Secret.
Leave it empty and the platform owns the certificate: the gateway controller
derives a name, self-issues a certificate under it and writes the derived name
back into this same Data key. A later read therefore projects the derived name
here. Clearing the field again removes the key, and the controller then derives
the same name from the connector's own name and writes it back, reusing the
certificate already stored under it, so clearing a platform-derived name is not
a way to force a rotation. Clearing a name you brought yourself is the real
handover: there the controller derives its own name and self-issues under it.
status.observability.gatewayCertSecretName reports the same single stored value,
alongside the other gateway observations.
observabilityGatewayCertSecretName string ​serviceType string ​
ServiceType selects the observability gateway Service type, ClusterIP or
LoadBalancer. Data key "serviceType". Empty keeps the key absent and means
ClusterIP, exactly how consumers treat a Secret without the key; the implied
default is deliberately not materialized so an untouched UI create and an API
create stay byte-identical.
serviceType string ​serviceAnnotations string ​
ServiceAnnotations is raw YAML text with flat "key: value" pairs merged into
the gateway Service's annotations. Data key "serviceAnnotations". The gateway
controller stamps them onto the Service whatever its type, and the value is
stored as sent for any serviceType; it only has a visible effect on a
LoadBalancer Service, where the cloud provider reads it. The UI drops the value
on save for other service types; the API keeps it.
serviceAnnotations string ​destinations string ​
Destinations is raw YAML text listing additional OTLP destinations the
gateway forwards to. Data key "destinations". Each entry has:
- name: unique, lowercase, up to 40 characters
- signal: metrics or logs
- endpoint: an http or https URL
- insecureSkipVerify: optional, skips TLS verification
- certSecretName: optional, a kubernetes.io/tls Secret for mTLS
The list is checked with the gateway controller's parser and stored as sent.
destinations string ​gatewayResources object ​
GatewayResources overrides the resource requests and limits of the gateway's
write container. Data key "gatewayResources", stored as the JSON serialization
of this value, which the gateway controller parses the same way it parses a YAML
block a hand-written Secret carries. Unset leaves the key absent and the
controller's defaults in effect. A stored value the controller could not parse
projects as unset; the controller reports that failure itself.
gatewayResources object ​limits object ​
Limits describes the maximum amount of compute resources allowed.
More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
limits object ​requests object ​
Requests describes the minimum amount of compute resources required.
If Requests is omitted for a container, it defaults to Limits if that is explicitly specified,
otherwise to an implementation-defined value. Requests cannot exceed Limits.
More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
requests object ​claims object[] ​
Claims lists the names of resources, defined in spec.resourceClaims,
that are used by this container.
This field depends on the
DynamicResourceAllocation feature gate.
This field is immutable. It can only be set for containers.
claims object[] ​name required string ​
Name must match the name of one entry in pod.spec.resourceClaims of
the Pod where this field is used. It makes that resource available
inside a container.
name required string ​request string ​
Request is the name chosen for a request in the referenced claim.
If empty, everything from the claim is made available, otherwise
only the result of this request.
request string ​queryProxyResources object ​
QueryProxyResources overrides the resource requests and limits of the gateway's
query proxy container. Data key "queryProxyResources"; the same storage and
parsing rules as gatewayResources apply.
queryProxyResources object ​limits object ​
Limits describes the maximum amount of compute resources allowed.
More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
limits object ​requests object ​
Requests describes the minimum amount of compute resources required.
If Requests is omitted for a container, it defaults to Limits if that is explicitly specified,
otherwise to an implementation-defined value. Requests cannot exceed Limits.
More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
requests object ​claims object[] ​
Claims lists the names of resources, defined in spec.resourceClaims,
that are used by this container.
This field depends on the
DynamicResourceAllocation feature gate.
This field is immutable. It can only be set for containers.
claims object[] ​name required string ​
Name must match the name of one entry in pod.spec.resourceClaims of
the Pod where this field is used. It makes that resource available
inside a container.
name required string ​request string ​
Request is the name chosen for a request in the referenced claim.
If empty, everything from the claim is made available, otherwise
only the result of this request.
request string ​status object ​
status object ​conditions object ​
Conditions holds the conditions observed for this connector. The list is open:
v1 names Configured, Reachable (and Authenticated where credentials fail
separately from connectivity) and Reconciled, but a controller may publish
other types.
The computed Configured condition reports the connector's own
metadata.creationTimestamp as its lastTransitionTime, unless a controller has
published a Configured in the same state, in which case that condition's
transition time is adopted. The API recomputes this condition on every read and
keeps no record of when the outcome last flipped, so the creation time is a
stand-in that the real transition can only have happened at or after, never a
transition the server observed.
conditions object ​observability object ​
Observability holds the observations that only the observability connector type
has and is set only when spec.type is observability. Its fields are what the
gateway controller reports, not a copy of the spec: the endpoint, CA and
certificate facts exist nowhere in the configuration. The other two types have no
type-specific facts in v1 and therefore have no status section of their own.
observability object ​gatewayEndpoint string ​
GatewayEndpoint is the address collectors send OTLP traffic to and the metrics
query proxy is reached at, taken from the gateway Service's load balancer
hostname or IP.
gatewayEndpoint string ​gatewayCA string ​
GatewayCA is the PEM-encoded CA certificate a collector must trust to talk to
the gateway, so it can be copied straight out of a connector into a collector
configuration.
gatewayCA string ​gatewayCertSecretName string ​
GatewayCertSecretName is the name of the kubernetes.io/tls Secret the
observability gateway is configured to serve, as stored on the connector: either
the one an admin brought through
spec.observability.observabilityGatewayCertSecretName, or the one the gateway
controller derived, self-issued and wrote back when that field was left empty.
It is the same single Data key the spec field is backed by, so the two can never
report different names; it is repeated here so a consumer reading status finds
the certificate reference next to the other gateway observations. Unlike the rest
of this section, which stays absent until a controller publishes it, the API
fills this field from the connector's stored configuration on every read, so no
controller has to publish it and a published copy never wins. It stays absent
until the gateway controller has written its derived name back: until then the
name in effect is the one the controller and the datasource consumers derive
from the connector name, and this field does not report it.
gatewayCertSecretName string ​certExpiresAt object ​
CertExpiresAt is the NotAfter of the certificate the gateway serves. It is a
pointer so an unpublished expiry is absent rather than the zero time, which
would read as a certificate that expired in year one.
certExpiresAt object ​certSelfIssued boolean ​
CertSelfIssued reports whether the platform issued the gateway certificate
itself rather than the admin bringing one. It is a pointer because false is a
meaningful answer here and must stay distinguishable from "no controller has
published cert facts yet".
certSelfIssued boolean ​Retrieve: Connectors​
You can either use curl or kubectl to retrieve Connectors.
- kubectl
- curl
Retrieve a list of Connectors​
Run the following command to list all Connectors:
kubectl get connectors.management.loft.sh -o yaml
Retrieve a single Connector by name​
Run the following kubectl command to get Connector shared-postgres:
kubectl get connectors.management.loft.sh shared-postgres -o yaml
Retrieve a list of Connectors​
Run the following curl command to list all Connectors:
curl -s "https://$LOFT_DOMAIN/kubernetes/management/apis/management.loft.sh/v1/connectors" \
-X GET --insecure \
-H "Authorization: Bearer $ACCESS_KEY"
Get a single Connector by name​
Run the following curl command to get Connector shared-postgres:
# Exchange shared-postgres in the url below with the name of the Connector
curl -s "https://$LOFT_DOMAIN/kubernetes/management/apis/management.loft.sh/v1/connectors/shared-postgres" \
-X GET --insecure \
-H "Authorization: Bearer $ACCESS_KEY"
Create: Connector​
You can either use curl or kubectl to create a new Connector.
- kubectl
- curl
Create a file object.yaml with the following contents:
apiVersion: management.loft.sh/v1
kind: Connector
metadata:
name: shared-postgres
spec:
displayName: Shared PostgreSQL
sharedDatabase:
dialect: postgres
endpoint: postgres.example.com
password: replace-with-database-password
port: "5432"
user: platform
status: {}
Then create the Connector shared-postgres with:
kubectl create -f object.yaml
Create a file object.yaml with the following contents:
apiVersion: management.loft.sh/v1
kind: Connector
metadata:
name: shared-postgres
spec:
displayName: Shared PostgreSQL
sharedDatabase:
dialect: postgres
endpoint: postgres.example.com
password: replace-with-database-password
port: "5432"
user: platform
status: {}
Run the following curl command to create a new Connector shared-postgres:
curl -s -X POST --insecure \
"https://$LOFT_DOMAIN/kubernetes/management/apis/management.loft.sh/v1/connectors" \
--data-binary "$(cat object.yaml)" \
-H "Content-Type: application/yaml" \
-H "Authorization: Bearer $ACCESS_KEY"
Update: Connector​
You can either use curl or kubectl to update Connectors.
- kubectl
- curl
Update Connector​
Run the following command to update Connector shared-postgres:
kubectl edit connectors.management.loft.sh shared-postgres
Then edit the object and upon save, kubectl will update the resource.
Patch Connector​
Patching a resource is useful if you want to generically exchange only a small portion of the object instead of retrieving the whole object first and then modifying it. To learn more about patches in Kubernetes, please take a look at the official docs.
Run the following kubectl command to add a new annotation my-annotation: my-value to the Connector shared-postgres via a patch:
kubectl patch connectors.management.loft.sh shared-postgres \
--type json \
-p '[{"op": "add", "path": "/metadata/annotations/my-annotation", "value": "my-value"}]'
Update Connector​
First retrieve the current object into a file object.yaml. This could look like:
apiVersion: management.loft.sh/v1
kind: Connector
metadata:
creationTimestamp: "2023-04-03T00:00:00Z"
generation: 12
name: shared-postgres
resourceVersion: "66325905"
uid: af5f9f0f-8ab9-4b4b-a595-a95a5921f3c2
spec:
displayName: Shared PostgreSQL
sharedDatabase:
dialect: postgres
endpoint: postgres.example.com
password: replace-with-database-password
port: "5432"
user: platform
status: {}
Run the following curl command to update a single Connector shared-postgres:
# Replace the shared-postgres in the url below with the name of the Connector you want to update
curl -s "https://$LOFT_DOMAIN/kubernetes/management/apis/management.loft.sh/v1/connectors/shared-postgres" \
-X PUT --insecure \
-H "Content-Type: application/yaml" \
-H "Authorization: Bearer $ACCESS_KEY" \
--data-binary "$(cat object.yaml)"
Patch Connector​
Patching a resource is useful if you want to generically exchange only a small portion of the object instead of retrieving the whole object first and then modifying it. To learn more about patches in Kubernetes, please take a look at the official docs.
Run the following curl command to add a new annotation my-annotation: my-value to the Connector shared-postgres via a patch:
# Replace the shared-postgres in the url below with the name of the Connector you want to update
curl -s "https://$LOFT_DOMAIN/kubernetes/management/apis/management.loft.sh/v1/connectors/shared-postgres" \
-X PATCH --insecure \
-H "Content-Type: application/json-patch+json" \
-H "Authorization: Bearer $ACCESS_KEY" \
--data '[{"op": "add", "path": "/metadata/annotations/my-annotation", "value": "my-value"}]'
Delete: Connector​
You can either use curl or kubectl to delete Connectors.
- kubectl
- curl
Run the following command to delete Connector shared-postgres:
kubectl delete connectors.management.loft.sh shared-postgres
Run the following curl command to delete Connector shared-postgres:
# Replace the shared-postgres in the url below with the name of the Connector you want to delete
curl -s "https://$LOFT_DOMAIN/kubernetes/management/apis/management.loft.sh/v1/connectors/shared-postgres" \
-X DELETE --insecure \
-H "Authorization: Bearer $ACCESS_KEY"