Documentation
¶
Overview ¶
Package k8s provides utilities for working with Kubernetes resources in tests.
This package includes helper functions for interacting with various Kubernetes resources such as StatefulSets, Deployments, Services, and more. It is designed to simplify common testing tasks, such as retrieving resources, waiting for resource readiness, and asserting resource states, by providing convenient wrappers around the Kubernetes client-go library.
Example usage:
import (
"testing"
"github.com/davidcollom/terratest-utils/pkg/k8s"
)
func TestStatefulSetReady(t *testing.T) {
options := k8s.NewKubectlOptions("", "", "default")
k8s.WaitForStatefulSetReady(t, options, "my-statefulset", "default", 5*time.Minute)
}
The package is intended for use in automated tests and supports both fatal and non-fatal error handling patterns.
Index ¶
- Variables
- func GetCustomResourceDefinition(t *testing.T, options *terrak8s.KubectlOptions, crdName string, ...) *apixv1.CustomResourceDefinition
- func GetCustomResourceDefinitionE(t *testing.T, options *terrak8s.KubectlOptions, crdName string, ...) (*apixv1.CustomResourceDefinition, error)
- func GetStatefulSet(t *testing.T, options *terrak8s.KubectlOptions, name, namespace string, ...) *appsv1.StatefulSet
- func GetStatefulSetE(t *testing.T, options *terrak8s.KubectlOptions, name, namespace string, ...) (*appsv1.StatefulSet, error)
- func IsCustomResourceDefinitionReady(crd *apixv1.CustomResourceDefinition) bool
- func IsStatefulSetUptoDate(sts *appsv1.StatefulSet) bool
- func ListCustomResourceDefinitionsE(t *testing.T, options *terrak8s.KubectlOptions, opts metav1.ListOptions) (*apixv1.CustomResourceDefinitionList, error)
- func ListStatefulSets(t *testing.T, options *terrak8s.KubectlOptions, opts metav1.ListOptions) []appsv1.StatefulSet
- func ListStatefulSetsE(t *testing.T, options *terrak8s.KubectlOptions, opts metav1.ListOptions) ([]appsv1.StatefulSet, error)
- func WaitForCustomResourceDefinitionIsReady(t *testing.T, options *terrak8s.KubectlOptions, crdName string, ...)
- func WaitForStatefulSetReady(t *testing.T, options *terrak8s.KubectlOptions, name, namespace string, ...)
Constants ¶
This section is empty.
Variables ¶
var NewAPIXClient = newAPIXClient
NewAPIXClient creates a new API Extensions (apix) clientset using the provided terrak8s.KubectlOptions. It returns an apixclientset.Interface for interacting with Kubernetes API extensions resources, or an error if the client could not be created. The testing.T object is used for test context and error reporting.
Parameters:
- t: The testing context, used for helper annotation and error reporting.
- options: The kubectl options containing cluster access configuration.
Returns:
- apixclientset.Interface: The API Extensions clientset for interacting with CRDs and other API extensions.
- error: An error if the configuration or clientset could not be created.
Example usage:
client, err := newAPIXClient(t, options)
require.NoError(t, err)
crds, err := client.ApiextensionsV1().CustomResourceDefinitions().List(context.TODO(), metav1.ListOptions{})
require.NoError(t, err)
var NewClient = terrak8s.GetKubernetesClientFromOptionsE
NewClient gets a new standard kubernetes clientset
Functions ¶
func GetCustomResourceDefinition ¶
func GetCustomResourceDefinition(t *testing.T, options *terrak8s.KubectlOptions, crdName string, opts metav1.GetOptions) *apixv1.CustomResourceDefinition
GetCustomResourceDefinition retrieves a Kubernetes CustomResourceDefinition (CRD) by name using the provided KubectlOptions. It fails the test immediately if the CRD cannot be retrieved, reporting the encountered error. Returns the retrieved CustomResourceDefinition object.
Parameters:
t - The testing context. options - The kubectl options to use for the request. crdName - The name of the CRD to retrieve.
Returns:
*apixv1.CustomResourceDefinition - The requested CRD object.
func GetCustomResourceDefinitionE ¶
func GetCustomResourceDefinitionE(t *testing.T, options *terrak8s.KubectlOptions, crdName string, opts metav1.GetOptions) (*apixv1.CustomResourceDefinition, error)
GetCustomResourceDefinitionE retrieves a Kubernetes CustomResourceDefinition (CRD) by name using the provided KubectlOptions. It returns the CRD object if found, or an error if the retrieval fails. This function is intended for use in tests and will mark the test as a helper.
Parameters:
- t: The testing context.
- options: The KubectlOptions to use for connecting to the cluster.
- crdName: The name of the CustomResourceDefinition to retrieve.
Returns:
- *apixv1.CustomResourceDefinition: The retrieved CRD object.
- error: An error if the CRD could not be retrieved.
func GetStatefulSet ¶ added in v0.0.6
func GetStatefulSet(t *testing.T, options *terrak8s.KubectlOptions, name, namespace string, opts metav1.GetOptions) *appsv1.StatefulSet
GetStatefulSet retrieves the specified StatefulSet from the given Kubernetes namespace using the provided KubectlOptions and GetOptions. It fails the test immediately if the StatefulSet cannot be retrieved, using require.NoError. Parameters:
- t: The testing context.
- options: The kubectl options to use when interacting with the cluster.
- name: The name of the StatefulSet to retrieve.
- namespace: The namespace where the StatefulSet is located.
- opts: Additional options for the get operation.
Returns:
- A pointer to the retrieved appsv1.StatefulSet object.
func GetStatefulSetE ¶ added in v0.0.6
func GetStatefulSetE(t *testing.T, options *terrak8s.KubectlOptions, name, namespace string, opts metav1.GetOptions) (*appsv1.StatefulSet, error)
GetStatefulSetE retrieves a Kubernetes StatefulSet resource by name and namespace using the provided KubectlOptions. It returns the StatefulSet object and an error if the retrieval fails. The function uses the testing context from t and allows passing custom metav1.GetOptions for the request.
Parameters:
- t: The testing context.
- options: The KubectlOptions to configure the Kubernetes client.
- name: The name of the StatefulSet to retrieve.
- namespace: The namespace where the StatefulSet resides.
- opts: Additional options for the Get request.
Returns:
- *appsv1.StatefulSet: The retrieved StatefulSet object.
- error: An error if the StatefulSet could not be retrieved.
func IsCustomResourceDefinitionReady ¶ added in v0.0.6
func IsCustomResourceDefinitionReady(crd *apixv1.CustomResourceDefinition) bool
IsCustomResourceDefinitionReady checks whether the given CustomResourceDefinition (CRD) is ready by verifying that both the 'Established' and 'NamesAccepted' conditions are true. It returns true if both conditions are met, indicating the CRD is fully established and its name has been accepted by the Kubernetes API server.
Parameters:
- crd: A pointer to the CustomResourceDefinition object to check.
Returns:
- bool: True if the CRD is ready (both 'Established' and 'NamesAccepted' conditions are true), false otherwise.
func IsStatefulSetUptoDate ¶ added in v0.0.6
func IsStatefulSetUptoDate(sts *appsv1.StatefulSet) bool
IsStatefulSetUptoDate checks whether the given StatefulSet has all its replicas updated, available, and current. It returns true if the number of updated, available, and current replicas all match the desired replica count.
Parameters:
- sts: A pointer to the appsv1.StatefulSet object to check.
Returns:
- bool: True if the StatefulSet is up-to-date (all replicas are updated, available, and current), false otherwise.
This function is useful for determining if a StatefulSet rollout has completed successfully.
func ListCustomResourceDefinitionsE ¶ added in v0.0.6
func ListCustomResourceDefinitionsE(t *testing.T, options *terrak8s.KubectlOptions, opts metav1.ListOptions) (*apixv1.CustomResourceDefinitionList, error)
ListCustomResourceDefinitionsE retrieves a list of CustomResourceDefinitions (CRDs) from the Kubernetes cluster using the provided KubectlOptions and ListOptions. It fails the test immediately if an error occurs.
Parameters:
- t: The testing context.
- options: The kubectl options specifying the Kubernetes context and namespace.
- opts: The list options to filter the CRDs.
Returns:
- A pointer to a CustomResourceDefinitionList containing the CRDs found in the cluster.
- error: An error if the list could not be retrieved.
func ListStatefulSets ¶ added in v0.0.6
func ListStatefulSets(t *testing.T, options *terrak8s.KubectlOptions, opts metav1.ListOptions) []appsv1.StatefulSet
ListStatefulSets retrieves a list of Kubernetes StatefulSets in the cluster using the provided KubectlOptions and ListOptions. It fails the test immediately if an error occurs during retrieval.
Parameters:
- t: The testing context.
- options: The kubectl options specifying the context and namespace.
- opts: The options to filter the list of StatefulSets.
Returns:
- A slice of appsv1.StatefulSet objects representing the StatefulSets found.
func ListStatefulSetsE ¶ added in v0.0.6
func ListStatefulSetsE(t *testing.T, options *terrak8s.KubectlOptions, opts metav1.ListOptions) ([]appsv1.StatefulSet, error)
ListStatefulSetsE retrieves a list of StatefulSets from the specified Kubernetes namespace using the provided KubectlOptions and ListOptions. It returns a slice of StatefulSet objects and an error if the retrieval fails. This function is intended for use in tests and will mark the test as a helper.
Parameters:
- t: The testing context.
- options: The kubectl options specifying the Kubernetes context and namespace.
- opts: The list options to filter the StatefulSets.
Returns:
- A slice of StatefulSet objects found in the specified namespace.
- An error if the StatefulSets could not be listed.
func WaitForCustomResourceDefinitionIsReady ¶ added in v0.0.6
func WaitForCustomResourceDefinitionIsReady(t *testing.T, options *terrak8s.KubectlOptions, crdName string, timeout time.Duration)
WaitForCustomResourceDefinitionIsReady waits until the specified CustomResourceDefinition (CRD) is ready in the Kubernetes cluster. It polls the CRD status at regular intervals until it is ready or the timeout is reached. If the CRD does not become ready within the given timeout, the test fails.
Parameters:
- t: The testing context.
- options: The kubectl options to use for connecting to the cluster.
- crdName: The name of the CRD to check for readiness.
- timeout: The maximum duration to wait for the CRD to become ready.
func WaitForStatefulSetReady ¶ added in v0.0.6
func WaitForStatefulSetReady(t *testing.T, options *terrak8s.KubectlOptions, name, namespace string, timeout time.Duration)
WaitForStatefulSetReady waits until the specified StatefulSet in the given namespace is ready or the timeout is reached. It polls the StatefulSet status every 2 seconds and checks if it is up-to-date using IsStatefulSetUptoDate. If the StatefulSet does not become ready within the timeout, the test fails with a fatal error.
Parameters:
- t: The testing context.
- options: The kubectl options for accessing the Kubernetes cluster.
- name: The name of the StatefulSet to check.
- namespace: The namespace where the StatefulSet is located.
- timeout: The maximum duration to wait for the StatefulSet to become ready.
Types ¶
This section is empty.
Source Files