Markers

This section defines the markers that kubetest makes available when installed.

Note

Use pytest --markers to get a complete list of available markers along with their descriptions.

Apply Manifest

Summary

@pytest.mark.applymanifest(path)

applymanifest allows you to load a Kubernetes manifest file and create the resource(s) on the cluster.

Description

Load the YAML manifest with the specified path and create the corresponding resource(s) on the cluster.

Loading a manifest via this marker does not prohibit you from manually loading other manifests later in the test case. You can use the kube fixture to get object references to the created resources. Manifests loaded via this marker are registered with the internal test case MetaInfo and can be waited upon for creation via the kube fixture’s wait_until_created method.

The path to the directory should either be an absolute path, or a path relative from the test file. This marker can be used multiple times on a test case. If you wish to load multiple manifests at once, consider using the Apply Manifests marker.

This marker is similar to the kubectl apply -f <file> command.

Examples

• Load a manifest YAML for a deployment

  @pytest.mark.applymanifest('./deployment.yaml')
  def test_something(kube):
      ...
  

• Load multiple manifests

  @pytest.mark.applymanifest('manifests/test/service.yaml')
  @pytest.mark.applymanifest('manifests/test/deployment.yaml')
  def test_something(kube):
      ...
  

Apply Manifests

Summary

@pytest.mark.applymanifests(dir, files=None)

applymanifests allows you to load Kubernetes manifests from the specified directory and create the resources on the cluster.

Description

Load the YAML manifests from the specified path and create the corresponding resources on the cluster. By default all YAML files found in the specified dir will be loaded and created. A list of file names can be passed to the files parameter, which would limit manifest application to only those YAMLs matching the provided file names in the directory.

Loading manifests via this marker does not prohibit you from manually loading other manifests later in the test case. You can use the kube fixture to get object references to the created resources. Manifests loaded via this marker are registered with the internal test case MetaInfo and can be waited upon for creation via the kube fixture’s wait_until_created method.

The path to the directory should either be an absolute path, or a path relative from the test file. This marker can be used multiple times on a test case.

When specifying specific files to use from within a directory, or when specifying multiple source directories, the order does not matter. The manifests are loaded, bucketed, and then applied to the cluster in the following order:

• Namespace
• RoleBinding
• ClusterRoleBinding
• Secret
• Service
• ConfigMap
• DeamonSet
• StatefulSet
• Deployment
• Pod

This marker is similar to the kubectl apply -f <dir> command.

Examples

• Load manifest YAMLs from a manifests directory

  @pytest.mark.applymanifests('manifests')
  def test_something(kube):
      ...
  

• Load specific manifest YAMLs from a manifests directory

  @pytest.mark.applymanifests('manifests', files=[
      'deployment.yaml',
      'service.yml'
  ])
  def test_something(kube):
      ...
  

• Load manifest YAMLs from a manifests directory and wait for the registered objects to be ready

  @pytest.mark.applymanifests('manifests')
  def test_something(kube):
      kube.wait_for_registered(timeout=60)
      ...
  

• Load manifests from multiple directories for a single test case

  @pytest.mark.applymanifests('manifests')
  @pytest.mark.applymanifests('common')
  def test_something(kube):
      ...
  

Cluster Role Binding

Summary

@pytest.mark.clusterrolebinding(name, subject_kind=None, subject_name=None)

clusterrolebinding creates a ClusterRoleBinding resource for the cluster which will exist for the lifespan of the test case. The named cluster role must already exist on the cluster.

Description

Create and use a Kubernetes ClusterRoleBinding for the test case. The generated ClusterRoleBinding will be automatically created and removed for each marked test. The name of the cluster role must be specified and the ClusterRole must already exist. This marker can be used multiple times on a test case.

Optionally, the subject_kind (one of: User, Group, ServiceAccount) and subject_name can be specified to set a custom target subject for the generated ClusterRoleBinding. If a custom target subject is specified, both subject_kind and subject_name must be specified. If no custom subject is specified, the generated ClusterRoleBinding will default to all users and all service accounts.

The ClusterRoleBinding created via this marker will always use an apiGroup of “rbac.authorization.k8s.io” for both subjects and roleRefs. Generated ClusterRoleBindings will be created with the kubetest: prefix.

For more information, see: https://kubernetes.io/docs/reference/access-authn-authz/rbac/

• To see all existing ClusterRoleBindings, use kubectl get clusterrolebindings
• To see all existing ClusterRoles, use kubectl get clusterroles

Examples

• Use the “cluster-admin” role binding with the default subject

  @pytest.mark.clusterrolebinding('cluster-admin')
  def test_something(kube):
    ...
  

• Use the “cluster-admin” role on a custom target subject

  @pytest.mark.clusterrolebinding('cluster-admin', subject_kind='ServiceAccount', subject_name='custom-acct')
  def test_something(kube):
      ...
  

• Set multiple ClusterRoleBindings for the test case

  @pytest.mark.clusterrolebinding('system:node')
  @pytest.mark.clusterrolebinding('system:discovery')
  def test_something(kube):
      ...
  

Role Binding

Summary

@pytest.mark.rolebinding(kind, name, subject_kind=None, subject_name=None)

rolebinding creates a RoleBinding resource for the cluster which will exist for the lifespan of the test case. The named role must already exist on the cluster.

Description

Create and use a Kubernetes RoleBinding for the test case. The generated RoleBinding will use the generated test case namespace and will be automatically created for each marked test case and removed once each test completes. The role kind (one of: Role, ClusterRole) must be specified along with the name of the role. Only existing Roles or ClusterRoles can be used. This marker can be used multiple times on a test case.

Optionally, the subject_kind (one of: User, Group, ServiceAccount) and subject_name can be specified to set a custom target subject for the generated RoleBinding. If a custom target subject is specified, both subject_kind and subject_name must be specified. If no custom subject is specified, the generated RoleBinding will default to all users in the namespace and all service accounts.

The RoleBinding created via this marker will always use an apiGroup of “rbac.authorization.k8s.io” for both subjects and roleRefs.

For more information, see: https://kubernetes.io/docs/reference/access-authn-authz/rbac/

• To see all existing RoleBindings, use kubectl get rolebindings
• To see all existing Roles, use kubectl get roles

Examples

• Use a RoleBinding with the default subject

  @pytest.mark.rolebinding('Role', 'test-role')
  def test_something(kube):
      ...
  

• Use a RoleBinding with a custom target subject

  @pytest.mark.rolebinding('Role', 'test-role', subject_kind='Group', subject_name='example')
  def test_something(kube):
      ...
  

• Set multiple RoleBindings for the test case

  @pytest.mark.rolebinding('Role', 'test-role')
  @pytest.mark.rolebinding('ClusterRole', 'custom-cluster-role')
  def test_something(kube):
      ...
  

Namespace

Summary

@pytest.mark.namespace(create=True, name=None)

namespace helps define the way namespaces are handled for each test case, allowing tests to define custom namespaces or use existing ones.

Description

The namespace marker exposes options to control how namespaces are handled by kubetest.

By default, a new namespace is created for each test case where the namespace name is generated from the test name and a timestamp to ensure uniqueness. With this marker, this default behavior may be overridden: - Set create to False to disable namespace creation. - Set name to a string to give the namespace a specific name, or set to None to use the generated name.

Note: When create is False, the objects created inside the test and by the applymanifest/applymanifests markers are not automatically deleted.

Examples

• Do not create a namespace for a given test

  @pytest.mark.namespace(create=False)
  def test_something(kube):
      ...
  

• Do not create a namespace and create all objects in the existing-ns namespace

  @pytest.mark.namespace(create=False, name='existing-ns')
  def test_something(kube):
      ...
  

• Create a namespace with a specific name

  @pytest.mark.namespace(create=True, name='specific-name')
  def test_something(kube):
      ...