Skip to content

APIExport

APIExport CRD schema reference (group apis.kcp.io)

APIExport registers an API and implementation to allow consumption by others through APIBindings.
Full name:
apiexports.apis.kcp.io
Group:
apis.kcp.io
Singular name:
apiexport
Plural name:
apiexports
Scope:
Cluster
Versions:
v1alpha1

Version v1alpha1

Properties

.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

.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

.metadata

object

.spec

object

Spec holds the desired state.

.spec.identity

object

identity points to a secret that contains the API identity in the ‘key’ file. The API identity determines an unique etcd prefix for objects stored via this APIExport.

Different APIExport in a workspace can share a common identity, or have different ones. The identity (the secret) can also be transferred to another workspace when the APIExport is moved.

The identity is a secret of the API provider. The APIBindings referencing this APIExport will store a derived, non-sensitive value of this identity.

The identity of an APIExport cannot be changed. A derived, non-sensitive value of the identity key is stored in the APIExport status and this value is immutable.

The identity is defaulted. A secret with the name of the APIExport is automatically created.

.spec.identity.secretRef

object

secretRef is a reference to a secret that contains the API identity in the ‘key’ file.

.spec.identity.secretRef.name

string

name is unique within a namespace to reference a secret resource.

.spec.identity.secretRef.namespace

string

namespace defines the space within which the secret name must be unique.

.spec.latestResourceSchemas

array

latestResourceSchemas records the latest APIResourceSchemas that are exposed with this APIExport.

The schemas can be changed in the life-cycle of the APIExport. These changes have no effect on existing APIBindings, but only on newly bound ones.

For updating existing APIBindings, use an APIDeployment keeping bound workspaces up-to-date.

.spec.latestResourceSchemas[*]

string

.spec.maximalPermissionPolicy

object

maximalPermissionPolicy will allow for a service provider to set an upper bound on what is allowed for a consumer of this API. If the policy is not set, no upper bound is applied, i.e the consuming users can do whatever the user workspace allows the user to do.

The policy consists of RBAC (Cluster)Roles and (Cluster)Bindings. A request of a user in a workspace that binds to this APIExport via an APIBinding is additionally checked against these rules, with the user name and the groups prefixed with apis.kcp.io:binding:.

For example: assume a user adam with groups system:authenticated and a-team binds to this APIExport in another workspace root:org:ws. Then a request in that workspace against a resource of this APIExport is authorized as every other request in that workspace, but in addition the RBAC policy here in the APIExport workspace has to grant access to the user apis.kcp.io:binding:adam with the groups apis.kcp.io:binding:system:authenticated and apis.kcp.io:binding:a-team.

.spec.maximalPermissionPolicy.local

object

local is the policy that is defined in same workspace as the API Export.

.spec.permissionClaims

array

permissionClaims make resources available in APIExport’s virtual workspace that are not part of the actual APIExport resources.

PermissionClaims are optional and should be the least access necessary to complete the functions that the service provider needs. Access is asked for on a GroupResource + identity basis.

PermissionClaims must be accepted by the user’s explicit acknowledgement. Hence, when claims change, the respecting objects are not visible immediately.

PermissionClaims overlapping with the APIExport resources are ignored.

.spec.permissionClaims[*]

object

PermissionClaim identifies an object by GR and identity hash. Its purpose is to determine the added permissions that a service provider may request and that a consumer may accept and allow the service provider access to.

.spec.permissionClaims[*].all

boolean

all claims all resources for the given group/resource. This is mutually exclusive with resourceSelector.

.spec.permissionClaims[*].group

string

group is the name of an API group. For core groups this is the empty string ‘“”’.

.spec.permissionClaims[*].identityHash

string

This is the identity for a given APIExport that the APIResourceSchema belongs to. The hash can be found on APIExport and APIResourceSchema’s status. It will be empty for core types. Note that one must look this up for a particular KCP instance.

.spec.permissionClaims[*].resource

string Required

resource is the name of the resource. Note: it is worth noting that you can not ask for permissions for resource provided by a CRD not provided by an api export.

.spec.permissionClaims[*].resourceSelector

array

resourceSelector is a list of claimed resource selectors.

.spec.permissionClaims[*].resourceSelector[*]

object

.spec.permissionClaims[*].resourceSelector[*].name

string

name of an object within a claimed group/resource. It matches the metadata.name field of the underlying object. If namespace is unset, all objects matching that name will be claimed.

.spec.permissionClaims[*].resourceSelector[*].namespace

string

namespace containing the named object. Matches metadata.namespace field. If “name” is unset, all objects from the namespace are being claimed.

.status

object

Status communicates the observed state.

.status.conditions

array

conditions is a list of conditions that apply to the APIExport.

.status.conditions[*]

object

Condition defines an observation of a object operational state.

.status.conditions[*].lastTransitionTime

string Required

Last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.

.status.conditions[*].message

string

A human readable message indicating details about the transition. This field may be empty.

.status.conditions[*].reason

string

The reason for the condition’s last transition in CamelCase. The specific API may choose whether or not this field is considered a guaranteed API. This field may not be empty.

.status.conditions[*].severity

string

Severity provides an explicit classification of Reason code, so the users or machines can immediately understand the current situation and act accordingly. The Severity field MUST be set only when Status=False.

.status.conditions[*].status

string Required

Status of the condition, one of True, False, Unknown.

.status.conditions[*].type

string Required

Type of condition in CamelCase or in foo.example.com/CamelCase. Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important.

.status.identityHash

string

identityHash is the hash of the API identity key of this APIExport. This value is immutable as soon as it is set.

.status.virtualWorkspaces

array

virtualWorkspaces contains all APIExport virtual workspace URLs.

Deprecated: use APIExportEndpointSlice.status.endpoints instead

.status.virtualWorkspaces[*]

object

.status.virtualWorkspaces[*].url

string Required

url is an APIExport virtual workspace URL.