kube

README

Go Declarative Testing - Kubernetes

gdt is a testing library that allows test authors to cleanly describe tests in a YAML file. gdt reads YAML files that describe a test's assertions and then builds a set of Go structures that the standard Go testing package can execute.

This github.com/gdt-dev/kube (shortened hereafter to gdt-kube) repository is a companion Go library for gdt that allows test authors to cleanly describe functional tests of Kubernetes resources and actions using a simple, clear YAML format. gdt-kube parses YAML files that describe Kubernetes client/API requests and assertions about those client calls.

Usage

gdt-kube is a Go library and is intended to be included in your own Go application's test code as a Go package dependency.

Import the gdt and gdt-kube libraries in a Go test file:

import (
    "github.com/gdt-dev/gdt"
    gdtkube "github.com/gdt-dev/kube"
)

In a standard Go test function, use the gdt.From() function to instantiate a test object (either a Scenario or a Suite) that can be Run() with a standard Go context.Context and a standard Go *testing.T type:

func TestExample(t *testing.T) {
    s, err := gdt.From("path/to/test.yaml")
    if err != nil {
        t.Fatalf("failed to load tests: %s", err)
    }

    ctx := context.Background()
    err = s.Run(ctx, t)
    if err != nil {
        t.Fatalf("failed to run tests: %s", err)
    }
}

To execute the tests, just run go test per the standard Go testing practice.

gdt is a declarative testing framework and the meat of your tests is going to be in the YAML files that describe the actions and assertions for one or more tests. Read on for an explanation of how to write tests in this declarative YAML format.

gdt-kube test file structure

A gdt test scenario (or just "scenario") is simply a YAML file.

All gdt scenarios have the following fields:

• name: (optional) string describing the contents of the test file. If missing or empty, the filename is used as the name
• description: (optional) string with longer description of the test file contents
• defaults: (optional) is a map, keyed by a plugin name, of default options and configuration values for that plugin.
• fixtures: (optional) list of strings indicating named fixtures that will be started before any of the tests in the file are run
• tests: list of Spec specializations that represent the runnable test units in the test scenario.

gdt-kube test configuration defaults

To set gdt-kube-specific default configuration values for the test scenario, set the defaults.kube field to an object containing any of these fields:

• defaults.kube.config: (optional) file path to a kubeconfig to use for the test scenario.
• defaults.kube.context: (optional) string containing the name of the kube context to use for the test scenario.
• defaults.kube.namespace: (optional) string containing the Kubernetes namespace to use when performing some action for the test scenario.

As an example, let's say that I wanted to override the Kubernetes namespace and the kube context used for a particular test scenario. I would do the following:

name: example-test-with-defaults
defaults:
  kube:
    context: my-kube-context
    namespace: my-namespace

gdt-kube test spec structure

All gdt test specs have the same [base fields][base-spec-fields]:

• name: (optional) string describing the test unit.
• description: (optional) string with longer description of the test unit.
• timeout: (optional) an object containing [timeout information][timeout] for the test unit.
• timeout: (optional) a string duration of time the test unit is expected to complete within.
• retry: (optional) an object containing retry configurationu for the test unit. Some plugins will automatically attempt to retry the test action when an assertion fails. This field allows you to control this retry behaviour for each individual test.
• retry.interval: (optional) a string duration of time that the test plugin will retry the test action in the event assertions fail. The default interval for retries is plugin-dependent.
• retry.attempts: (optional) an integer indicating the number of times that a plugin will retry the test action in the event assertions fail. The default number of attempts for retries is plugin-dependent.
• retry.exponential: (optional) a boolean indicating an exponential backoff should be applied to the retry interval. The default is is plugin-dependent.
• wait (optional) an object containing wait information for the test unit.
• wait.before: a string duration of time that gdt should wait before executing the test unit's action.
• wait.after: a string duration of time that gdt should wait after executing the test unit's action.

gdt-kube test specs have some additional fields that allow you to take some action against a Kubernetes API and assert that the response from the API matches some expectation:

• config: (optional) file path to the kubeconfig to use for this specific test. This allows you to override the defaults.config value from the test scenario.
• context: (optional) string containing the name of the kube context to use for this specific test. This allows you to override the defaults.context value from the test scenario.
• namespace: (optional) string containing the name of the Kubernetes namespace to use when performing some action for this specific test. This allows you to override the defaults.namespace value from the test scenario.
• kube: (optional) an object containing actions and assertions the test takes against the Kubernetes API server.
• kube.get: (optional) string or object containing a resource identifier (e.g. pods, po/nginx or label selector for resources that will be read from the Kubernetes API server.
• kube.create: (optional) string containing either a file path to a YAML manifest or a string of raw YAML containing the resource(s) to create.
• kube.apply: (optional) string containing either a file path to a YAML manifest or a string of raw YAML containing the resource(s) for which gdt-kube will perform a Kubernetes Apply call.
• kube.delete: (optional) string or object containing either a resource identifier (e.g. pods, po/nginx , a file path to a YAML manifest, or a label selector for resources that will be deleted.
• var: (optional) an object describing variables that can have values saved and referred to by subsequent test specs. Each key in the var object is the name of the variable to define.
• var.$VARIABLE_NAME.from: (required) a JSONPath expression describing where the variable with name $VARIABLE_NAME should source its value from the Kubernetes resource returned in a kubectl get response.
• assert: (optional) object containing assertions to make about the action performed by the test.
• assert.require: (optional) a boolean indicating whether a failed assertion will cause the test scenario's execution to stop. The default behaviour of gdt is to continue execution of subsequent test specs in a test scenario when an assertion fails.
• assert.error: (optional) string to match a returned error from the Kubernetes API server.
• assert.len: (optional) int with the expected number of items returned.
• assert.notfound: (optional) bool indicating the test author expects the Kubernetes API to return a 404/Not Found for a resource.
• assert.unknown: (optional) bool indicating the test author expects the Kubernetes API server to respond that it does not know the type of resource attempting to be fetched or created.
• assert.matches: (optional) a YAML string, a filepath, or a map[string]interface{} representing the content that you expect to find in the returned result from the kube.get call. If assert.matches is a string, the string can be either a file path to a YAML manifest or inline an YAML string containing the resource fields to compare. Only fields present in the Matches resource are compared. There is a check for existence in the retrieved resource as well as a check that the value of the fields match. Only scalar fields are matched entirely. In other words, you do not need to specify every field of a struct field in order to compare the value of a single field in the nested struct.
• assert.conditions: (optional) a map, keyed by ConditionType string, of any of the following:
  • a string containing the Status value that the Condition with the ConditionType should have.
  • a list of strings containing the Status value that the Condition with the ConditionType should have.
  • an object containing two fields:
    • status which itself is either a single string or a list of strings containing the Status values that the Condition with the ConditionType should have
    • reason which is the exact string that should be present in the Condition with the ConditionType
• assert.placement: (optional) an object describing assertions to make about the placement (scheduling outcome) of Pods returned in the kube.get result.
• assert.placement.spread: (optional) an single string or array of strings for topology keys that the Pods returned in the kube.get result should be spread evenly across, e.g. topology.kubernetes.io/zone or kubernetes.io/hostname.
• assert.placement.pack: (optional) an single string or array of strings for topology keys that the Pods returned in the kube.get result should be bin-packed within, e.g. topology.kubernetes.io/zone or kubernetes.io/hostname.
• assert.json: (optional) object describing the assertions to make about resource(s) returned from the kube.get call to the Kubernetes API server.
• assert.json.len: (optional) integer representing the number of bytes in the resulting JSON object after successfully parsing the resource.
• assert.json.paths: (optional) map of strings where the keys of the map are JSONPath expressions and the values of the map are the expected value to be found when evaluating the JSONPath expression
• assert.json.path-formats: (optional) map of strings where the keys of the map are JSONPath expressions and the values of the map are the expected format of the value to be found when evaluating the JSONPath expression. See the list of valid format strings
• assert.json.schema: (optional) string containing a filepath to a JSONSchema document. If present, the resource's structure will be validated against this JSONSChema document.

Examples

Here are some examples of gdt-kube tests.

Testing that a Pod with the name nginx exists:

name: test-nginx-pod-exists
tests:
 - kube:
     get: pods/nginx
 # These are equivalent. "kube.get" is a shortcut for the longer object.field
 # form above.
 - kube.get: pods/nginx

Testing that a Pod with the name nginx does not exist:

name: test-nginx-pod-not-exist
tests:
 - kube:
     get: pods/nginx
   assert:
     notfound: true

Testing that there are two Pods having the label app:nginx:

name: list-pods-with-labels
tests:
  # You can use the shortcut kube.get
  - name: verify-pods-with-app-nginx-label
    kube.get:
      type: pods
      labels:
        app: nginx
    assert:
      len: 2
  # Or the long-form kube:get
  - name: verify-pods-with-app-nginx-label
    kube:
      get:
        type: pods
        labels:
          app: nginx
    assert:
      len: 2
  # Like "kube.get", you can pass a label selector for "kube.delete"
  - kube.delete:
      type: pods
      labels:
        app: nginx
  # And you can use the long-form kube:delete as well
  - kube:
      delete:
        type: pods
        labels:
          app: nginx

Testing that a Pod with the name nginx exists by the specified timeout (essentially, gdt-kube will retry the get call and assertion until the end of the timeout):

name: test-nginx-pod-exists-within-1-minute
tests:
 - kube.get: pods/nginx
   timeout: 1m

Testing creation and subsequent fetch then delete of a Pod, specifying the Pod definition contained in a YAML file:

name: create-get-delete-pod
description: create, get and delete a Pod
fixtures:
  - kind
tests:
  - name: create-pod
    kube:
      create: manifests/nginx-pod.yaml
  - name: pod-exists
    kube:
      get: pods/nginx
  - name: delete-pod
    kube:
      delete: pods/nginx

Testing creation and subsequent fetch then delete of a Pod, specifying the Pod definition using an inline YAML blob:

name: create-get-delete-pod
description: create, get and delete a Pod
fixtures:
  - kind
tests:
  # "kube.create" is a shortcut for the longer object->field format
  - kube.create: |
        apiVersion: v1
        kind: Pod
        metadata:
          name: nginx
        spec:
          containers:
          - name: nginx
            image: nginx
            imagePullPolicy: IfNotPresent
  # "kube.get" is a shortcut for the longer object->field format
  - kube.get: pods/nginx
  # "kube.delete" is a shortcut for the longer object->field format
  - kube.delete: pods/nginx

Using label selectors

When selecting objects from the Kubernetes API, you can use a label selector in the kube.get and kube.delete test spec actions. This label selector functionality is incredibly flexible. You can use a kubectl-style label selector string, like so:

 - name: select pods that have the "app=argo" label but do NOT have the "app=argo-rollouts" or "app=argorollouts" label
   kube:
     get:
       type: pod
       labels: app in (argo),app notin (argo-rollouts,argorollouts)

The kube.get.labels field can also be a map of string to string, which is more aligned with how gdt's YAML syntax is structured. This example selects pods that have both the app=myapp and the region=myregion label:

 - name: select pods that have BOTH the app=myapp AND region=myregion label
   kube:
     get:
       type: pod
       labels:
         app: myapp
         region: myregion

The kube.get.labels-in field is a map of string to slice of strings and gets translated into a "label IN (val1, val2)" expression. This example selects pods that have either the app=myapp label or the app=test label:

 - name: select pods that have EITHER the app=myapp OR app=test label
   kube:
     get:
       type: pod
       labels-in:
         app:
          - myapp
          - test

The kube.get.labels-not-in field is also a map of string to slice of strings and gets translated into a label NOTIN (val1, val2) expression. This example selects pods that do not have either the app=myapp or the app=test label.

 - name: select pods that have DON'T HAVE the app=myapp OR app=test label
   kube:
     get:
       type: pod
       labels-not-in:
         app:
          - myapp
          - test

You can combine the kube.get.labels, kube.get.labels-in and kube.get.labels-not-in fields to create complex querying expressions. This example selects pods that have the app=myapp label and have either the category=test or category=staging label and do not have a personal=true label:

 - name: select pods that have have an app=myapp label AND have either a category=test or category=staging label AND do not have the personal=true label
   kube:
     get:
       type: pod
       labels:
         app: myapp
       labels-in:
         category:
          - test
          - staging
       labels-not-in:
         personal:
          - true

Passing variables to subsequent test specs

A gdt test scenario is comprised of a list of test specs. These test specs are executed in sequential order. If you want to have one test spec be able to use some output or value calculated or asserted in a previous step, you can use the gdt variable system.

Here's a test scenario that shows how to define variables in a test spec and how to use those variables in later test specs.

file: testdata/var-save-restore.yaml:

name: var-save-restore
description: scenario showing different variations of variable definition and references
defaults:
  kube:
    namespace: var-save-restore
tests:
  - name: create-pod
    kube:
      create: testdata/manifests/nginx-pod.yaml

  - name: define a variable and populate it with the pod's IP address
    kube:
      get: pods/nginx
    assert:
      conditions:
        ready:
          status: true
    var:
      POD_IP:
        from: $.status.podIP
      POD_NAME:
        from: $.metadata.name

  - name: get the pod's information and assert same values as variables
    kube.get: pods/$$POD_NAME
    assert:
      matches:
        status:
          podIP: $$POD_IP

  - name: delete-pod
    kube:
      delete: pods/$$POD_NAME

In the first test spec, we create new Pod by specifying the filepath to a Kubernetes manifest (testdata/manifests/nginx-pod.yaml):

  - name: create-pod
    kube:
      create: testdata/manifests/nginx-pod.yaml

In the second test spec, we get the Pod that we created in the first step, asserting that the Pod is in a Ready state:

  - name: define a variable and populate it with the pod's IP address
    kube:
      get: pods/nginx
    assert:
      conditions:
        ready:
          status: true

The assert.conditions.ready.status=true means that the above test spec will not succeed until the Pod is in a Ready state.

NOTE: Pods that are in a Ready state have their status.podIP field set to a non-empty value.

In the same second test spec, we add a var: section to define two variables that we can refer to in subsequent test specs:

    var:
      POD_IP:
        from: $.status.podIP
      POD_NAME:
        from: $.metadata.name

The above creates two variables. The first variable is named POD_IP and will get its value from the field in the returned Pod resource representation at the JSONPath $.status.podIP. The second variable is named POD_NAME and gets its value from the field in the Pod resource representation at the JSONPath $.metadata.name.

NOTE: People familiar with using kubectl get ... -o jsonpath=EXPRESSION should find this syntax easy to understand. Just remember that in gdt (and proper JSONPath expressions), you must begin the JSONPath expression with the $. characters instead of the kubectl behaviour of beginning the JSONPath expression with the {. characters.

If you do something like this to get a Pod's IP using kubectl:

kubectl get pod/my-pod -o jsonpath='{.status.podIP}'

You would do the following in a gdt-kube test spec:

from: $.status.podIP

Having defined the POD_IP and POD_NAME variables, you can then refer to the values contained in those variables in subsequent gdt test specs by using the double-dollar-sign notation.

NOTE: We use the double-dollar-sign notation because by default, gdt replaces all single-dollar-sign notations with environment variables BEFORE executing the test specs in a test scenario. Using the double-dollar-sign notation means that environment variable substitution does not impact the referencing of gdt variables referenced in a test spec.

In the third test spec, you see an example of referring to the POD_NAME variable in the kube.get field:

  - name: get the pod's information and assert same values as variables
    kube.get: pods/$$POD_NAME

as well as an example of referring to the POD_IP variable in the assert field of that same test spec:

    assert:
      matches:
        status:
          podIP: $$POD_IP

Finally, the fourth test spec demonstrates that you can continue to refer to a variable defined in any previous test spec. In the fourth test spec, we refer to the POD_NAME variable from the kube.delete field:

  - name: delete-pod
    kube:
      delete: pods/$$POD_NAME

Executing arbitrary commands or shell scripts

You can mix other gdt test types in a single gdt test scenario. For example, here we are testing the creation of a Pod, waiting a little while with the wait.after directive, then using the gdt exec test type to test SSH connectivity to the Pod.

name: create-check-ssh
description: create a Deployment then check SSH connectivity
fixtures:
  - kind
tests:
  - kube.create: manifests/deployment.yaml
    wait:
      after: 30s
  - exec: ssh -T someuser@ip

Note that you can make use of the gdt variable system to pass values between gdt test specs, as this example demonstrates:

file: testdata/curl-pod-ip.yaml

name: curl-pod-ip
description: scenario showing how to create two NGinx Pods and test connectivity to internal Pod IP addresses
fixtures:
  - kind
defaults:
  kube:
    namespace: curl-pod-ip
tests:
  - name: create-server
    kube:
      create: testdata/manifests/nginx-server.yaml

  - name: get-server-pod-ip
    kube:
      get: pods/server
    assert:
      conditions:
        ready:
          status: true
    var:
      SERVER_IP:
        from: $.status.podIP

  - name: create-connect-tester
    kube:
      create: testdata/manifests/nginx-connect-test.yaml

  - name: wait-connect-test-ready
    kube:
      get: pods/connect-test
    assert:
      conditions:
        ready:
          status: true

  - name: curl-server-from-connect-tester
    exec: kubectl exec -n curl-pod-ip pods/connect-test -- curl -s -I -v $$SERVER_IP
    timeout: 2s
    assert:
      out:
        contains: "200 OK"
      # curl -v causes output to be sent to stderr that looks like this:
      # * Connected to 10.244.0.17 (10.244.0.17) port 80 (#0)
      # > GET / HTTP/1.1
      # > Host: 10.244.0.17
      # > User-Agent: curl/7.88.1
      # > Accept: */*
      # >
      # < HTTP/1.1 200 OK
      err:
        contains: "Host: $$SERVER_IP"

  - name: delete-connect-tester
    kube:
      delete: pods/connect-test

  - name: delete-server
    kube:
      delete: pods/server

In the above example, we use a few gdt-kube test specs (the ones with kube: field in the test spec definition) along with an exec test spec that executes curl from a test Pod that a previous test spec creates and the command that the test spec executes references the SERVER_IP variable defined in the second step:

  - name: curl-server-from-connect-tester
    exec: kubectl exec -n curl-pod-ip pods/connect-test -- curl -s -I -v $$SERVER_IP

You can see that the assert: field in the exec test spec references the SERVER_IP variable:

      err:
        contains: "Host: $$SERVER_IP"

Asserting resource fields using assert.matches

The assert.matches field of a gdt-kube test Spec allows a test author to specify expected fields and those field contents in a resource that was returned by the Kubernetes API server from the result of a kube.get call.

Suppose you have a Deployment resource and you want to write a test that checks that a Deployment resource's Status.ReadyReplicas field is 2.

You do not need to specify all other Deployment.Status fields like Status.Replicas in order to match the Status.ReadyReplicas field value. You only need to include the Status.ReadyReplicas field in the Matches value as these examples demonstrate:

tests:
 - name: check deployment's ready replicas is 2
   kube:
     get: deployments/my-deployment
   assert:
     matches: |
       kind: Deployment
       metadata:
         name: my-deployment
       status:
         readyReplicas: 2

you don't even need to include the kind and metadata in assert.matches. If missing, no kind and name matching will be performed.

tests:
 - name: check deployment's ready replicas is 2
   kube:
     get: deployments/my-deployment
   assert:
     matches: |
       status:
         readyReplicas: 2

In fact, you don't need to use an inline multiline YAML string. You can use a map[string]interface{} as well:

tests:
 - name: check deployment's ready replicas is 2
   kube:
     get: deployments/my-deployment
   assert:
     matches:
       status:
         readyReplicas: 2

Asserting resource Conditions using assert.conditions

assertion.conditions contains the assertions to make about a resource's Status.Conditions collection. It is a map, keyed by the ConditionType (matched case-insensitively), of assertions to make about that Condition. The assertions can be:

• a string which is the ConditionStatus that should be found for that Condition
• a list of strings containing ConditionStatuses, any of which should be found for that Condition
• an object of type ConditionExpect that contains more fine-grained assertions about that Condition's Status and Reason

A simple example that asserts that a Pod's Ready Condition has a status of True. Note that both the condition type ("Ready") and the status ("True") are matched case-insensitively, which means you can just use lowercase strings:

tests:
 - kube:
     get: pods/nginx
   assert:
     conditions:
       ready: true

If we wanted to assert that the ContainersReady Condition had a status of either False or Unknown, we could write the test like this:

tests:
 - kube:
     get: pods/nginx
   assert:
     conditions:
       containersReady:
        - false
        - unknown

Finally, if we wanted to assert that a Deployment's Progressing Condition had a Reason field with a value "NewReplicaSetAvailable" (matched case-sensitively), we could do the following:

tests:
 - kube:
     get: deployments/nginx
   assert:
     conditions:
       progressing:
         status: true
         reason: NewReplicaSetAvailable

Asserting scheduling outcomes using assert.placement

The assert.placement field of a gdt-kube test Spec allows a test author to specify the expected scheduling outcome for a set of Pods returned by the Kubernetes API server from the result of a kube.get call.

Asserting even spread of Pods across a topology

Suppose you have a Deployment resource with a TopologySpreadConstraints that specifies the Pods in the Deployment must land on different hosts:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
       - name: nginx
         image: nginx:latest
         ports:
          - containerPort: 80
      topologySpreadConstraints:
       - maxSkew: 1
         topologyKey: kubernetes.io/hostname
         whenUnsatisfiable: DoNotSchedule
         labelSelector:
           matchLabels:
             app: nginx

You can create a gdt-kube test case that verifies that your nginx Deployment's Pods are evenly spread across all available hosts:

tests:
 - kube:
     get: deployments/nginx
   assert:
     placement:
       spread: kubernetes.io/hostname

If there are more hosts than the spec.replicas in the Deployment, gdt-kube will ensure that each Pod landed on a unique host. If there are fewer hosts than the spec.replicas in the Deployment, gdt-kube will ensure that there is an even spread of Pods to hosts, with any host having no more than one more Pod than any other.

Asserting bin-packing of Pods

Suppose you have configured your Kubernetes scheduler to bin-pack Pods onto hosts by scheduling Pods to hosts with the most allocated CPU resources:

apiVersion: kubescheduler.config.k8s.io/v1
kind: KubeSchedulerConfiguration
profiles:
- pluginConfig:
  - args:
      scoringStrategy:
        resources:
        - name: cpu
          weight: 100
        type: MostAllocated
    name: NodeResourcesFit

You can create a gdt-kube test case that verifies that your nginx Deployment's Pods are packed onto the fewest unique hosts:

tests:
 - kube:
     get: deployments/nginx
   assert:
     placement:
       pack: kubernetes.io/hostname

gdt-kube will examine the total number of hosts that meet the nginx Deployment's scheduling and resource constraints and then assert that the number of hosts the Deployment's Pods landed on is the minimum number that would fit the total requested resources.

Asserting resource fields using assert.json

The assert.json field of a gdt-kube test Spec allows a test author to specify expected fields, the value of those fields as well as the format of field values in a resource that was returned by the Kubernetes API server from the result of a kube.get call.

Suppose you have a Deployment resource and you want to write a test that checks that a Deployment resource's Status.ReadyReplicas field is 2.

You can specify this expectation using the assert.json.paths field, which is a map[string]interface{} that takes map keys that are JSONPath expressions and map values of what the field at that JSONPath expression should contain:

tests:
 - name: check deployment's ready replicas is 2
   kube:
     get: deployments/my-deployment
   assert:
     json:
       paths:
         $.status.readyReplicas: 2 

JSONPath expressions can be fairly complex, allowing the test author to, for example, assert the value of a nested map field with a particular key, as this example shows:

tests:
 - name: check deployment's pod template "app" label is "nginx"
   kube:
     get: deployments/my-deployment
   assert:
     json:
       paths:
         $.spec.template.labels["app"]: nginx

You can check that the value of a particular field at a JSONPath is formatted in a particular fashion using assert.json.path-formats. This is a map, keyed by JSONPath expression, of the data format the value of the field at that JSONPath expression should have. Valid data formats are:

• date
• date-time
• email
• hostname
• idn-email
• ipv4
• ipv6
• iri
• iri-reference
• json-pointer
• regex
• relative-json-pointer
• time
• uri
• uri-reference
• uri-template
• uuid
• uuid4

Read more about JSONSchema formats.

For example, suppose we wanted to verify that a Deployment's metadata.uid field was a UUID-4 and that its metadata.creationTimestamp field was a date-time timestamp:

tests:
  - kube:
      get: deployments/nginx
    assert:
      json:
        path-formats:
          $.metadata.uid: uuid4
          $.metadata.creationTimestamp: date-time

Updating a resource and asserting corresponding field changes

Here is an example of creating a Deployment with an initial spec.replicas count of 2, then applying a change to spec.replicas of 1, then asserting that the status.readyReplicas gets updated to 1.

file testdata/manifests/nginx-deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 2
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx
        ports:
        - containerPort: 80

file testdata/apply-deployment.yaml:

name: apply-deployment
description: create, get, apply a change, get, delete a Deployment
fixtures:
  - kind
tests:
  - name: create-deployment
    kube:
      create: testdata/manifests/nginx-deployment.yaml
  - name: deployment-has-2-replicas
    timeout:
      after: 20s
    kube:
      get: deployments/nginx
    assert:
      matches:
        status:
          readyReplicas: 2
  - name: apply-deployment-change
    kube:
      apply: |
        apiVersion: apps/v1
        kind: Deployment
        metadata:
          name: nginx
        spec:
          replicas: 1
  - name: deployment-has-1-replica
    timeout:
      after: 20s
    kube:
      get: deployments/nginx
    assert:
      matches:
        status:
          readyReplicas: 1
  - name: delete-deployment
    kube:
      delete: deployments/nginx

Determining Kubernetes config, context and namespace values

When evaluating how to construct a Kubernetes client gdt-kube uses the following precedence to determine the kubeconfig and kube context:

1. The individual test spec's config or context value
2. Any gdt Fixture that exposes a gdt.kube.config or gdt.kube.context state key (e.g. [KindFixture][kind-fixture]).
3. The test file's defaults.kube config or context value.

For the kubeconfig file path, if none of the above yielded a value, the following precedence is used to determine the kubeconfig:

1. A non-empty KUBECONFIG environment variable pointing at a file.
2. In-cluster config if running in cluster.
3. $HOME/.kube/config if it exists.

gdt-kube Fixtures

gdt Fixtures are objects that help set up and tear down a testing environment. The gdt-kube library has some utility fixtures to make testing with Kubernetes easier.

KindFixture

The KindFixture eases integration of gdt-kube tests with the KinD local Kubernetes development system.

To use it, import the gdt-kube/fixtures/kind package:

import (
    "github.com/gdt-dev/gdt"
    gdtkube "github.com/gdt-dev/kube"
    gdtkind "github.com/gdt-dev/kube/fixtures/kind"
)

and then register the fixture with your gdt Context, like so:

func TestExample(t *testing.T) {
    s, err := gdt.From("path/to/test.yaml")
    if err != nil {
        t.Fatalf("failed to load tests: %s", err)
    }

    ctx := context.Background()
    ctx = gdt.RegisterFixture(ctx, "kind", gdtkind.New())
    err = s.Run(ctx, t)
    if err != nil {
        t.Fatalf("failed to run tests: %s", err)
    }
}

In your test file, you would list the "kind" fixture in the fixtures list:

name: example-using-kind
fixtures:
 - kind
tests:
 - kube.get: pods/nginx

Retaining and deleting KinD clusters

The default behaviour of the KindFixture is to delete the KinD cluster when the Fixture's Stop() method is called, but only if the KinD cluster did not previously exist before the Fixture's Start() method was called.

If you want to always ensure that a KinD cluster is deleted when the KindFixture is stopped, use the fixtures.kind.WithDeleteOnStop() function:

import (
    "github.com/gdt-dev/gdt"
    gdtkube "github.com/gdt-dev/kube"
    gdtkind "github.com/gdt-dev/kube/fixtures/kind"
)

func TestExample(t *testing.T) {
    s, err := gdt.From("path/to/test.yaml")
    if err != nil {
        t.Fatalf("failed to load tests: %s", err)
    }

    ctx := context.Background()
    ctx = gdt.RegisterFixture(
        ctx, "kind", gdtkind.New(),
        gdtkind.WithDeleteOnStop(),
    )
    err = s.Run(ctx, t)
    if err != nil {
        t.Fatalf("failed to run tests: %s", err)
    }
}

Likewise, the default behaviour of the KindFixture is to retain the KinD cluster when the Fixture's Stop() method is called but only if the KinD cluster previously existed before the Fixture's Start() method was called.

If you want to always ensure a KinD cluster is retained, even if the KindFixture created the KinD cluster, use the fixtures.kind.WithRetainOnStop() function:

import (
    "github.com/gdt-dev/gdt"
    gdtkube "github.com/gdt-dev/kube"
    gdtkind "github.com/gdt-dev/kube/fixtures/kind"
)

func TestExample(t *testing.T) {
    s, err := gdt.From("path/to/test.yaml")
    if err != nil {
        t.Fatalf("failed to load tests: %s", err)
    }

    ctx := context.Background()
    ctx = gdt.RegisterFixture(
        ctx, "kind", gdtkind.New(),
        gdtkind.WithRetainOnStop(),
    )
    err = s.Run(ctx, t)
    if err != nil {
        t.Fatalf("failed to run tests: %s", err)
    }
}

Passing a KinD configuration

You may want to pass a custom KinD configuration resource by using the fixtures.kind.WithConfigPath() modifier:

import (
    "github.com/gdt-dev/gdt"
    gdtkube "github.com/gdt-dev/kube"
    gdtkind "github.com/gdt-dev/kube/fixtures/kind"
)

func TestExample(t *testing.T) {
    s, err := gdt.From("path/to/test.yaml")
    if err != nil {
        t.Fatalf("failed to load tests: %s", err)
    }

    configPath := filepath.Join("testdata", "my-kind-config.yaml")

    ctx := context.Background()
    ctx = gdt.RegisterFixture(
        ctx, "kind", gdtkind.New(),
        gdtkind.WithConfigPath(configPath),
    )
    err = s.Run(ctx, t)
    if err != nil {
        t.Fatalf("failed to run tests: %s", err)
    }
}

Contributing and acknowledgements

gdt was inspired by Gabbi, the excellent Python declarative testing framework. gdt tries to bring the same clear, concise test definitions to the world of Go functional testing.

The Go gopher logo, from which gdt's logo was derived, was created by Renee French.

Contributions to gdt-kube are welcomed! Feel free to open a Github issue or submit a pull request.

Documentation

Index

• Constants
• Variables
• func ConditionDoesNotMatch(msg string) error
• func ConnectError(err error) error
• func EitherShortcutOrKubeSpecAt(node *yaml.Node) error
• func ExpectedNotFound(msg string) error
• func InvalidConditionMatchAt(err error, node *yaml.Node) error
• func InvalidMatchesAt(node *yaml.Node) error
• func InvalidMatchesUnmarshalErrorAt(err error, node *yaml.Node) error
• func InvalidResourceSpecifierAt(subject string, node *yaml.Node) error
• func InvalidResourceSpecifierOrFilepathAt(subject string, node *yaml.Node) error
• func InvalidWithLabelsAt(err error, node *yaml.Node) error
• func KubeConfigNotFoundAt(path string, node *yaml.Node) error
• func MatchesNotEqual(msg string) error
• func MoreThanOneKubeActionAt(node *yaml.Node) error
• func Plugin() api.Plugin
• func ResourceUnknown(arg string) error
• func WithLabelsOnlyGetDeleteAt(node *yaml.Node) error
• type Action
  • func (a *Action) Do(ctx context.Context, c *connection, ns string, out *interface{}) error
  • func (a *Action) UnmarshalYAML(node *yaml.Node) error
• type ConditionMatch
  • func (m *ConditionMatch) UnmarshalYAML(node *yaml.Node) error
• type Defaults
  • func (d *Defaults) Merge(vals map[string]any)
  • func (d *Defaults) UnmarshalYAML(node *yaml.Node) error
• type Expect
  • func (e *Expect) UnmarshalYAML(node *yaml.Node) error
• type KubeSpec
  • func (s *KubeSpec) UnmarshalYAML(node *yaml.Node) error
• type PlacementAssertion
• type ResourceIdentifier
  • func NewResourceIdentifier(arg string, name string, labels map[string]string) (*ResourceIdentifier, error)
  • func (r *ResourceIdentifier) Title() string
  • func (r *ResourceIdentifier) UnmarshalYAML(node *yaml.Node) error
• type ResourceIdentifierOrFile
  • func NewResourceIdentifierOrFile(fp string, arg string, name string, labels map[string]string) (*ResourceIdentifierOrFile, error)
  • func (r *ResourceIdentifierOrFile) FilePath() string
  • func (r *ResourceIdentifierOrFile) Title() string
  • func (r *ResourceIdentifierOrFile) UnmarshalYAML(node *yaml.Node) error
• type Spec
  • func (s *Spec) Base() *api.Spec
  • func (s *Spec) Config(ctx context.Context) (*rest.Config, error)
  • func (s *Spec) Eval(ctx context.Context) (*api.Result, error)
  • func (s *Spec) Namespace() string
  • func (s *Spec) Retry() *api.Retry
  • func (s *Spec) SetBase(b api.Spec)
  • func (s *Spec) Timeout() *api.Timeout
  • func (s *Spec) Title() string
  • func (s *Spec) UnmarshalYAML(node *yaml.Node) error
• type VarEntry
  • func (e *VarEntry) UnmarshalYAML(node *yaml.Node) error
• type Variables

Constants

const (
	// StateKeyConfig holds a file path to a kubeconfig
	StateKeyConfig = "kube.config"
	// StateKeyConfigBytes holds a KUBECONFIG object in a bytearray
	StateKeyConfigBytes = "kube.config.bytes"
	// StateKeyContext holds a string kubecontext name
	StateKeyContext = "kube.context"
)

Variables

var (
	// ErrResourceUnknown is returned when an unknown resource kind is
	// specified for a create/apply/delete target. This is a runtime error
	// because we rely on the discovery client to determine whether a resource
	// kind is valid.
	ErrResourceUnknown = fmt.Errorf(
		"%w: resource unknown",
		api.ErrFailure,
	)
	// ErrExpectedNotFound is returned when we expected to get either a
	// NotFound response code (get) or an empty set of results (list) but did
	// not find that.
	ErrExpectedNotFound = fmt.Errorf(
		"%w: expected not found",
		api.ErrFailure,
	)
	// ErrMatchesNotEqual is returned when we failed to match a resource to an
	// object field in a `kube.assert.matches` object.
	ErrMatchesNotEqual = fmt.Errorf(
		"%w: match field not equal",
		api.ErrFailure,
	)
	// ErrConditionDoesNotMatch is returned when we failed to match a resource to an
	// Condition match expression in a `kube.assert.matches` object.
	ErrConditionDoesNotMatch = fmt.Errorf(
		"%w: condition does not match expectation",
		api.ErrFailure,
	)
	// ErrConnect is returned when we failed to create a client config to
	// connect to the Kubernetes API server.
	ErrConnect = fmt.Errorf(
		"%w: k8s connect failure",
		api.RuntimeError,
	)
)

var (
	// DefaultTimeout is the default timeout used for each individual test
	// spec. Note that gdt's top-level Scenario.Run handles all timeout and
	// retry behaviour.
	DefaultTimeout = "5s"
)

Functions

func ConditionDoesNotMatch

func ConditionDoesNotMatch(msg string) error

ConditionDoesNotMatch returns ErrConditionDoesNotMatch when a `kube.assert.conditions` object did not match the returned resource.

func ConnectError

func ConnectError(err error) error

ConnectError returns ErrConnnect when an error is found trying to construct a Kubernetes client connection.

func EitherShortcutOrKubeSpecAt

func EitherShortcutOrKubeSpecAt(node *yaml.Node) error

EitherShortcutOrKubeSpecAt returns a parse error indicating the test author included both a shortcut (e.g. `kube.create` or `kube.apply`) AND the long-form `kube` object in the same test spec.

func ExpectedNotFound

func ExpectedNotFound(msg string) error

ExpectedNotFound returns ErrExpectedNotFound for a given status code or number of items.

func InvalidConditionMatchAt

func InvalidConditionMatchAt(err error, node *yaml.Node) error

InvalidConditionMatchAtreturn a parse error indicating the `Kube.Assert.Conditions` value is malformed.

func InvalidMatchesAt

func InvalidMatchesAt(node *yaml.Node) error

InvalidMatchesAt returns a parse error indicating the `Kube.Assert.Matches` value is malformed.

func InvalidMatchesUnmarshalErrorAt

func InvalidMatchesUnmarshalErrorAt(err error, node *yaml.Node) error

InvalidMatchesUnmarshalErrorAt returns a parse error indicating the `Kube.Assert.Matches` value is malformed and we could not unmarshal it.

func InvalidResourceSpecifierAt

func InvalidResourceSpecifierAt(subject string, node *yaml.Node) error

InvalidResourceSpecifierAt returns a parse error indicating the test author uses a resource specifier for the `kube.get` or `kube.delete` fields that is not valid.

func InvalidResourceSpecifierOrFilepathAt

func InvalidResourceSpecifierOrFilepathAt(
	subject string, node *yaml.Node,
) error

InvalidResourceSpecifierOrFilepathAt returns a parse error indicating the test author uses a resource specifier for the `kube.delete` fields that is not valid or is not a filepath.

func InvalidWithLabelsAt

func InvalidWithLabelsAt(err error, node *yaml.Node) error

InvalidWithLabelsAt returns a parse error indicating the test author included `kube.with.labels` but did not specify either `kube.get` or `kube.delete`.

func KubeConfigNotFoundAt

func KubeConfigNotFoundAt(path string, node *yaml.Node) error

KubeConfigNotFoundAt returns a parse error indicating a kubeconfig path points to a file that does not exist.

func MatchesNotEqual

func MatchesNotEqual(msg string) error

MatchesNotEqual returns ErrMatchesNotEqual when a `kube.assert.matches` object did not match the returned resource.

func MoreThanOneKubeActionAt

func MoreThanOneKubeActionAt(node *yaml.Node) error

MoreThanOneKubeActionAt returns a parse error indicating the test author included more than one Kubernetes action (e.g. `create` or `apply`) in the same KubeSpec.

func Plugin

func Plugin() api.Plugin

Plugin returns the Kubernetes gdt plugin

func ResourceUnknown

func ResourceUnknown(arg string) error

ResourceUnknown returns ErrRuntimeResourceUnknown for a given resource or kind arg string

func WithLabelsOnlyGetDeleteAt

func WithLabelsOnlyGetDeleteAt(node *yaml.Node) error

WithLabelsOnlyGetDeleteAt returns a parse error indicating the test author included `kube.with.labels` but did not specify either `kube.get` or `kube.delete`.

Types

type Action

type Action struct {
	// Create is a string containing a file path or raw YAML content describing
	// a Kubernetes resource to call `kubectl create` with.
	Create string `yaml:"create,omitempty"`
	// Apply is a string containing a file path or raw YAML content describing
	// a Kubernetes resource to call `kubectl apply` with.
	Apply string `yaml:"apply,omitempty"`
	// Delete is a string or object containing arguments to `kubectl delete`.
	//
	// It must be one of the following:
	//
	// - a file path to a manifest that will be read and the resources
	//   described in the manifest will be deleted
	// - a resource kind or kind alias, e.g. "pods", "po", followed by one of
	//   the following:
	//   * a space or `/` character followed by the resource name to delete
	//     only a resource with that name.
	// - an object with a `type` and optional `labels` field containing a label
	//   selector that should be used to select that `type` of resource.
	Delete *ResourceIdentifierOrFile `yaml:"delete,omitempty"`
	// Get is a string or object containing arguments to `kubectl get`.
	//
	// It must be one of the following:
	//
	// - a string with a resource kind or kind alias, e.g. "pods", "po",
	//   followed by one of the following:
	//   * a space or `/` character followed by the resource name to get only a
	//     resource with that name.
	// - an object with a `type` and optional `labels` field containing a label
	//   selector that should be used to select that `type` of resource.
	Get *ResourceIdentifier `yaml:"get,omitempty"`
}

Action describes the the Kubernetes-specific action that is performed by the test.

func (*Action) Do

func (a *Action) Do(
	ctx context.Context,
	c *connection,
	ns string,
	out *interface{},
) error

Do performs a single kube command, returning any runtime error.

`kubeErr` will be filled with any error received from the Kubernetes client call.

`out` will be filled with the contents of the command's output, if any. When the command is a Get, `out` will be a `*unstructured.Unstructured`. When the command is a List, `out` will be a `*unstructured.UnstructuredList`.

func (*Action) UnmarshalYAML

func (a *Action) UnmarshalYAML(node *yaml.Node) error

type ConditionMatch

type ConditionMatch struct {
	// contains filtered or unexported fields
}

ConditionMatch can be a string (the ConditionStatus to match), a slice of strings (any of the ConditionStatus values to match) or an object with Status and Reason fields describing the Condition fields we want to match on.

func (*ConditionMatch) UnmarshalYAML

func (m *ConditionMatch) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML is a custom unmarshaler that understands that the value of the ConditionMatch can be either a string, a slice of strings, or an object with .

type Defaults

type Defaults struct {
	// contains filtered or unexported fields
}

Defaults is the known kube plugin defaults collection

func (*Defaults) Merge

func (d *Defaults) Merge(vals map[string]any)

Merge merges the supplies map of key/value combinations with the set of handled defaults for the plugin. The supplied key/value map will NOT be unpacked from its top-most plugin named element. So, for example, the kube plugin should expect to get a map that looks like "kube:namespace:<namespace>" and not "namespace:<namespace>".

func (*Defaults) UnmarshalYAML

func (d *Defaults) UnmarshalYAML(node *yaml.Node) error

type Expect

type Expect struct {
	// Require indicates that any failed assertion should stop the execution of
	// the test scenario in which the test spec is contained.
	Require bool `yaml:"require,omitempty"`
	// Error is a string that is expected to be returned as an error string
	// from the client call
	// TODO(jaypipes): Make this polymorphic to be either a shortcut string
	// (like this) or a struct containing individual error assertion fields.
	Error string `yaml:"error,omitempty"`
	// Len is an integer that is expected to represent the number of items in
	// the response when the Get request was translated into a List operation
	// (i.e. when the resource specified was a plural kind
	Len *int `yaml:"len,omitempty"`
	// NotFound is a bool indicating the result of a call should be a
	// NotFound error. Alternately, the user can set `assert.len = 0` and for
	// single-object-returning calls (e.g. `get` or `delete`) the assertion is
	// equivalent to `assert.notfound = true`
	NotFound bool `yaml:"notfound,omitempty"`
	// Unknown is a bool indicating the test author expects that they will have
	// gotten an error ("the server could not find the requested resource")
	// from the Kubernetes API server. This is mostly good for unit/fuzz
	// testing CRDs.
	Unknown bool `yaml:"unknown,omitempty"`
	// Matches is either a string or a map[string]any containing the
	// resource that the `Kube.Get` should match against. If Matches is a
	// string, the string can be either a file path to a YAML manifest or
	// inline an YAML string containing the resource fields to compare.
	//
	// Only fields present in the Matches resource are compared. There is a
	// check for existence in the retrieved resource as well as a check that
	// the value of the fields match. Only scalar fields are matched entirely.
	// In other words, you do not need to specify every field of a struct field
	// in order to compare the value of a single field in the nested struct.
	//
	// As an example, imagine you wanted to check that a Deployment resource's
	// `Status.ReadyReplicas` field was 2. You do not need to specify all other
	// `Deployment.Status` fields like `Status.Replicas` in order to match the
	// `Status.ReadyReplicas` field value. You only need to include the
	// `Status.ReadyReplicas` field in the `Matches` value as these examples
	// demonstrate:
	//
	// “`yaml
	// tests:
	//  - name: check deployment's ready replicas is 2
	//    kube:
	//      get: deployments/my-deployment
	//      assert:
	//        matches: |
	//          kind: Deployment
	//          metadata:
	//            name: my-deployment
	//          status:
	//            readyReplicas: 2
	// “`
	//
	// you don't even need to include the kind and metadata in `Matches`. If
	// missing, no kind and name matching will be performed.
	//
	// “`yaml
	// tests:
	//  - name: check deployment's ready replicas is 2
	//    kube:
	//      get: deployments/my-deployment
	//      assert:
	//        matches: |
	//          status:
	//            readyReplicas: 2
	// “`
	//
	// In fact, you don't need to use an inline multiline YAML string. You can
	// use a `map[string]any` as well:
	//
	// “`yaml
	// tests:
	//  - name: check deployment's ready replicas is 2
	//    kube:
	//      get: deployments/my-deployment
	//      assert:
	//        matches:
	//          status:
	//            readyReplicas: 2
	// “`
	Matches any `yaml:"matches,omitempty"`
	// JSON contains the assertions about JSON data in a response from the
	// Kubernetes API server.
	JSON *gdtjson.Expect `yaml:"json,omitempty"`
	// Conditions contains the assertions to make about a resource's
	// `Status.Conditions` collection. It is a map, keyed by the ConditionType
	// (matched case-insensitively), of assertions to make about that
	// Condition. The assertions can be:
	//
	// * a string which is the ConditionStatus that should be found for that
	//   Condition
	// * a list of strings containing ConditionStatuses, any of which should be
	//   found for that Condition.
	// * an object of type `ConditionExpect` that contains more fine-grained
	//   assertions about that Condition.
	//
	// A simple example that asserts that a Pod's `Ready` Condition has a
	// status of `True`. Note that both the condition type ("Ready") and the
	// status ("True") are matched case-insensitively, which means you can just
	// use lowercase strings:
	//
	// “`yaml
	// tests:
	//  - kube:
	//      get: pods/nginx
	//      assert:
	//        conditions:
	//          ready: true
	// “`
	//
	// If we wanted to assert that the `ContainersReady` Condition had a status
	// of either `False` or `Unknown`, we could write the test like this:
	//
	// “`yaml
	// tests:
	//  - kube:
	//      get: pods/nginx
	//      assert:
	//        conditions:
	//          containersReady:
	//           - false
	//           - unknown
	// “`
	//
	// Finally, if we wanted to assert that a Deployment's `Progressing`
	// Condition had a Reason field with a value "NewReplicaSetAvailable"
	// (matched case-sensitively), we could do the following:
	//
	// “`yaml
	// tests:
	//  - kube:
	//      get: deployments/nginx
	//      assert:
	//        conditions:
	//          progressing:
	//            status: true
	//            reason: NewReplicaSetAvailable
	// “`
	Conditions map[string]*ConditionMatch `yaml:"conditions,omitempty"`
	// Placement describes expected Pod scheduling spread or pack outcomes.
	Placement *PlacementAssertion `yaml:"placement,omitempty"`
}

Expect contains one or more assertions about a kube client call

func (*Expect) UnmarshalYAML

func (e *Expect) UnmarshalYAML(node *yaml.Node) error

type KubeSpec

type KubeSpec struct {
	Action
	// Config is the path of the kubeconfig to use in executing Kubernetes
	// client calls for this Spec. If empty, the `kube` defaults' `config`
	// value will be used. If that is empty, the following precedence is used:
	//
	// 1) KUBECONFIG environment variable pointing at a file.
	// 2) In-cluster config if running in cluster.
	// 3) $HOME/.kube/config if exists.
	Config string `yaml:"config,omitempty"`
	// Context is the name of the kubecontext to use for this Spec. If empty,
	// the `kube` defaults' `context` value will be used. If that is empty, the
	// kubecontext marked default in the kubeconfig is used.
	Context string `yaml:"context,omitempty"`
	// Namespace is a string indicating the Kubernetes namespace to use when
	// calling the Kubernetes API. If empty, any namespace specified in the
	// Defaults is used and then the string "default" is used.
	Namespace string `yaml:"namespace,omitempty"`
}

KubeSpec is the complex type containing all of the Kubernetes-specific actions. Most users will use the `kube.create`, `kube.apply` and `kube.describe` shortcut fields.

func (*KubeSpec) UnmarshalYAML

func (s *KubeSpec) UnmarshalYAML(node *yaml.Node) error

type PlacementAssertion

type PlacementAssertion struct {
	// Spread contains zero or more topology keys that gdt-kube will assert an
	// even spread across.
	Spread *api.FlexStrings `yaml:"spread,omitempty"`
	// Pack contains zero or more topology keys that gdt-kube will assert
	// bin-packing of resources within.
	Pack *api.FlexStrings `yaml:"pack,omitempty"`
}

PlacementAssertion describes an expectation for Pod scheduling outcomes.

type ResourceIdentifier

type ResourceIdentifier struct {
	Arg           string              `yaml:"-"`
	Name          string              `yaml:"-"`
	LabelSelector kubelabels.Selector `yaml:"-"`
}

ResourceIdentifier is a struct used to parse an interface{} that can be either a string or a struct containing a selector with things like a label key/value map.

func NewResourceIdentifier

func NewResourceIdentifier(
	arg string,
	name string,
	labels map[string]string,
) (*ResourceIdentifier, error)

func (*ResourceIdentifier) Title

func (r *ResourceIdentifier) Title() string

Title returns the resource identifier's kind and name, if present

func (*ResourceIdentifier) UnmarshalYAML

func (r *ResourceIdentifier) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML is a custom unmarshaler that understands that the value of the ResourceIdentifier can be either a string or a selector.

type ResourceIdentifierOrFile

type ResourceIdentifierOrFile struct {
	Arg           string              `yaml:"-"`
	Name          string              `yaml:"-"`
	LabelSelector kubelabels.Selector `yaml:"-"`
	// contains filtered or unexported fields
}

ResourceIdentifierOrFile is a struct used to parse an interface{} that can be either a string, a filepath or a struct containing a selector with things like a label key/value map.

func NewResourceIdentifierOrFile

func NewResourceIdentifierOrFile(
	fp string,
	arg string,
	name string,
	labels map[string]string,
) (*ResourceIdentifierOrFile, error)

func (*ResourceIdentifierOrFile) FilePath

func (r *ResourceIdentifierOrFile) FilePath() string

FilePath returns the resource identifier's file path, if present

func (*ResourceIdentifierOrFile) Title

func (r *ResourceIdentifierOrFile) Title() string

Title returns the resource identifier's file name, if present, or the kind and name, if present

func (*ResourceIdentifierOrFile) UnmarshalYAML

func (r *ResourceIdentifierOrFile) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML is a custom unmarshaler that understands that the value of the ResourceIdentifierOrFile can be either a string or a selector.

type Spec

type Spec struct {
	api.Spec
	// Kube is the complex type containing all of the Kubernetes-specific
	// actions and assertions. Most users will use the `kube.create`,
	// `kube.apply` and `kube.describe` shortcut fields.
	Kube *KubeSpec `yaml:"kube,omitempty"`
	// KubeCreate is a shortcut for the `KubeSpec.Create`. It can contain
	// either a file path or raw YAML content describing a Kubernetes resource
	// to call `kubectl create` with.
	KubeCreate string `yaml:"kube.create,omitempty"`
	// KubeGet is a string containing an argument to `kubectl get` and must be
	// one of the following:
	//
	// - a file path to a manifest that will be read and the resources within
	//   retrieved via `kubectl get`
	// - a resource kind or kind alias, e.g. "pods", "po", followed by one of
	//   the following:
	//   * a space or `/` character followed by the resource name to get only a
	//     resource with that name.
	//   * a space followed by `-l ` followed by a label to get resources
	//     having such a label.
	KubeGet string `yaml:"kube.get,omitempty"`
	// KubeApply is a shortcut for the `KubeSpec.Apply`. It is a string
	// containing a file path or raw YAML content describing a Kubernetes
	// resource to call `kubectl apply` with.
	KubeApply string `yaml:"kube.apply,omitempty"`
	// KubeDelete is a shortcut for the `KubeSpec.Delete`. It is a string
	// containing an argument to `kubectl delete` and must be one of the
	// following:
	//
	// - a file path to a manifest that will be read and the resources
	//   described in the manifest will be deleted
	// - a resource kind or kind alias, e.g. "pods", "po", followed by one of
	//   the following:
	//   * a space or `/` character followed by the resource name to delete
	//     only a resource with that name.
	//   * a space followed by `-l ` followed by a label to delete resources
	//     having such a label.
	//   * the string `--all` to delete all resources of that kind.
	KubeDelete string `yaml:"kube.delete,omitempty"`
	// Require is an object containing the conditions that the Spec will
	// assert. If any condition fails, the test scenario execution will stop
	// and be marked as failed.
	Require *Expect `yaml:"require,omitempty"`
	// Assert houses the various assertions to be made about the kube client
	// call (Create, Apply, Get, etc)
	// TODO(jaypipes): Make this polymorphic to be either a single assertion
	// struct or a list of assertion structs
	Assert *Expect `yaml:"assert,omitempty"`
	// Var allows the test author to save arbitrary data to the test scenario,
	// facilitating the passing of variables between test specs potentially
	// provided by different gdt Plugins.
	Var Variables `yaml:"var,omitempty"`
}

Spec describes a test of a *single* Kubernetes API request and response.

func (*Spec) Base

func (s *Spec) Base() *api.Spec

func (*Spec) Config

func (s *Spec) Config(ctx context.Context) (*rest.Config, error)

Config returns a Kubernetes client-go rest.Config to use for this Spec. We evaluate where to retrieve the Kubernetes config from by looking at the following things, in this order:

1) The Spec.Kube.Config value 2) Any Fixtures that return a `kube.config` or `kube.config.bytes` state key 3) The Defaults.Config value 4) KUBECONFIG environment variable pointing at a file. 5) In-cluster config if running in cluster. 6) $HOME/.kube/config if exists.

func (*Spec) Eval

func (s *Spec) Eval(ctx context.Context) (*api.Result, error)

Eval performs an action and evaluates the results of that action, returning a Result that informs the Scenario about what failed or succeeded. A new Kubernetes client request is made during this call.

func (*Spec) Namespace

func (s *Spec) Namespace() string

Namespace returns the Kubernetes namespace to use when calling the Kubernetes API server. We evaluate which namespace to use by looking at the following things, in this order:

1) The Spec.Kube.Namespace value 2) The Defaults.Namespace value 3) Use the string "default"

func (*Spec) Retry

func (s *Spec) Retry() *api.Retry

func (*Spec) SetBase

func (s *Spec) SetBase(b api.Spec)

func (*Spec) Timeout

func (s *Spec) Timeout() *api.Timeout

func (*Spec) Title

func (s *Spec) Title() string

Title returns a good name for the Spec

func (*Spec) UnmarshalYAML

func (s *Spec) UnmarshalYAML(node *yaml.Node) error

type VarEntry

type VarEntry struct {
	// From is a string that indicates where the value of the variable will be
	// sourced from. This string is a JSONPath expression that contains
	// instructions on how to extract a particular field from a Kubernetes
	// resource fetched in the `kube.get` command.
	From string `yaml:"from"`
}

func (*VarEntry) UnmarshalYAML

func (e *VarEntry) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML is a custom unmarshaler that ensures that JSONPath expressions contained in the VarEntry are valid.

type Variables

type Variables map[string]VarEntry

Variables allows the test author to save arbitrary data to the test scenario, facilitating the passing of variables between test specs potentially provided by different gdt Plugins.