ApiToken - Create OAuth access tokens for accessing the Quay Container Registry API

The ApiToken custom resource relies on a Secret resource to provide the connection parameters to the Quay instance. This Secret resource must include the following data:

  • host: URL for accessing the Quay API, such as https://quay.example.com:8443 for example.
  • validateCerts: Whether to allow insecure connections to the API. By default, insecure connections are refused.
  • username: The username to use for authenticating against the API.
  • password: The password to use for authenticating against the API.

In contrast to the other custom resources, you cannot authenticate by using an existing OAuth access token, and the secret must provide the username and the password parameters. The OAuth access token that the ApiToken custom resource generates acts on behalf of the user account that you use in this secret.

You can create the secret by using the kubectl create secret command:

kubectl create secret generic quay-credentials --from-literal host=https://quay.example.com:8443 --from-literal validateCerts=false --from-literal username=admin --from-literal password=Sup3r53cr3L

Or you can create the secret from a resource file:

---
apiVersion: v1
kind: Secret
metadata:
  name: quay-credentials
stringData:
  host: https://quay.example.com:8443
  validateCerts: "false"
  username: admin
  password: Sup3r53cr3L

You refer to this secret in your ApiToken custom resource by using the connSecretRef property. See the usage example.

The ApiToken custom resource generates an OAuth access token for authenticating against the API, and stores it in the Secret resource that you specify by using the retSecretRef property. You can use that secret as an input for other custom resources, by specifying it in the connSecretRef property of these resources.

Usage Example

---
apiVersion: quay.herve4m.github.io/v1alpha1
kind: ApiToken
metadata:
  name: apitoken-sample
spec:
  # Connection parameters in a Secret resource
  # The secret MUST include the "username" and "password" parameters, because
  # you cannot authenticate with a token to create another token.
  connSecretRef:
    name: quay-credentials
    # By default, the operator looks for the secret in the same namespace as
    # the apitoken resource, but you can specify a different namespace.
    # namespace: mynamespace

  # You can specify the client ID by using the clientId parameter, or you can
  # refer to a secret that stores the ID by using the clientIdFrom parameter.
  # The application resource can create such secret.
  # clientId: PZ6F80R1LCVPGYNZGSZQ
  clientIdFrom:
    name: application-secret
    key: clientId
    # namespace: mynamespace

  rights:
    - all
    # - org:admin
    # - user:admin

  # The Secret resource is created or updated, and stores the "accessToken"
  # parameter.
  # "host", "validateCerts", and "token" parameters are also added, so that
  # you can use the secret with other Quay resources to access the API.
  retSecretRef:
    name: quay-credentials-secret
    # By default, the operator stores the secret in the same namespace as the
    # apitoken resource, but you can specify a different namespace.
    # namespace: mynamespace

Properties

clientId

The client ID associated with the OAuth application to use for generating the OAuth access token. See the Application resource to create an application object and to retrieve the associated client ID.

Type: string

Required: False

Default value: None

clientIdFrom

Reference to the secret resource that stores the client ID of the application. You specify the key that stores this client ID by using the key parameter. By default the operator looks for a clientId key in the secret. Mutually exclusive with clientId.

Type: object (see the following properties)

Required: False

Default value: None

clientIdFrom.key

In the secret resource, key that stores the client ID.

Type: string

Required: False

Default value: clientId

clientIdFrom.name

Name of the secret resource.

Type: string

Required: True

Default value: None

clientIdFrom.namespace

Namespace of the secret resource. By default, the secret resource is retrieved from the same namespace as the current ApiToken resource.

Type: string

Required: False

Default value: None

connSecretRef

Reference to the secret resource that stores the connection parameters to the Quay Container Registry API. The secret must include the host, token (or username and password), and optionally the validateCerts keys.

Type: object (see the following properties)

Required: True

Default value: None

connSecretRef.name

Name of the secret resource.

Type: string

Required: True

Default value: None

connSecretRef.namespace

Namespace of the secret resource. By default, the secret resource is retrieved from the same namespace as the current ApiToken resource.

Type: string

Required: False

Default value: None

forUser

The username to generate an OAuth access token for. The user receives a notification in the web interface, which enables the user to retrieve the token. When you use this option, the resource does not return the token. Requires Quay version 3.12 or later.

Type: string

Required: False

Default value: None

preserveInQuayOnDeletion

Whether to preserve the corresponding Quay object when you delete the ApiToken resource. When set to false (the default), the object is deleted from Quay.

Type: boolean

Required: False

Default value: False

retSecretRef

RetSecretRef is the secret resource that the ApiToken resource creates. This secret will store the data that the resource generates:

  • accessToken - The OAuth access token.
  • token - The OAuth access token (copy).
  • host - URL for accessing the Quay API.
  • validateCerts - Whether to allow insecure connections to the API.

Type: object (see the following properties)

Required: False

Default value: None

retSecretRef.name

Name of the secret resource.

Type: string

Required: True

Default value: None

retSecretRef.namespace

Namespace of the secret resource. By default, the secret resource is created in the same namespace as the current ApiToken resource.

Type: string

Required: False

Default value: None

rights

List of permissions to grant to the user account. all means all the permissions.

Type: array

Required: False

Default value: ['repo:read']

Listing the ApiToken Resources

You can retrieve the list of the ApiToken custom resources in a namespace by using the kubectl get command:

kubectl get apitokens.quay.herve4m.github.io -n <namespace>