Getting Started

OpenShift Origin includes a client library and API object definitions which can be used to interact with its REST API from the Go programming language.

Both the client library and API object definitions are versioned, with separate branches corresponding to major versions of OpenShift Origin. It is recommended to match the client library version you use to the version of OpenShift Origin with which you are interacting.

It is also recommended to use Glide to manage your Go libraries: if you do so, Glide will automatically ensure that OpenShift Origin client library and its dependencies will be included in your project.

The following example connects to OpenShift Origin using a pre-existing kubeconfig file, then lists all pods and builds in the current namespace. Copy it as main.go into a new directory under your GOPATH.

$GOPATH/src/gettingstarted/main.go
package main

import (
        "fmt"

        buildv1client "github.com/openshift/client-go/build/clientset/versioned/typed/build/v1"

        metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
        corev1client "k8s.io/client-go/kubernetes/typed/core/v1"
        "k8s.io/client-go/tools/clientcmd"
)

func main() {
        // Instantiate loader for kubeconfig file.
        kubeconfig := clientcmd.NewNonInteractiveDeferredLoadingClientConfig(
                clientcmd.NewDefaultClientConfigLoadingRules(),
                &clientcmd.ConfigOverrides{},
        )

        // Determine the Namespace referenced by the current context in the
        // kubeconfig file.
        namespace, _, err := kubeconfig.Namespace()
        if err != nil {
                panic(err)
        }

        // Get a rest.Config from the kubeconfig file.  This will be passed into all
        // the client objects we create.
        restconfig, err := kubeconfig.ClientConfig()
        if err != nil {
                panic(err)
        }

        // Create a Kubernetes core/v1 client.
        coreclient, err := corev1client.NewForConfig(restconfig)
        if err != nil {
                panic(err)
        }

        // Create an OpenShift build/v1 client.
        buildclient, err := buildv1client.NewForConfig(restconfig)
        if err != nil {
                panic(err)
        }

        // List all Pods in our current Namespace.
        pods, err := coreclient.Pods(namespace).List(metav1.ListOptions{})
        if err != nil {
                panic(err)
        }

        fmt.Printf("Pods in namespace %s:\n", namespace)
        for _, pod := range pods.Items {
                fmt.Printf("  %s\n", pod.Name)
        }

        // List all Builds in our current Namespace.
        builds, err := buildclient.Builds(namespace).List(metav1.ListOptions{})
        if err != nil {
                panic(err)
        }

        fmt.Printf("Builds in namespace %s:\n", namespace)
        for _, build := range builds.Items {
                fmt.Printf("  %s\n", build.Name)
        }
}

In addition, Glide must be configured to include the OpenShift Origin client library at the appropriate version. Copy the following as glide.yaml in the same directory as the file above.

$GOPATH/src/gettingstarted/glide.yaml
package: gettingstarted (1)
import:
- package: github.com/openshift/client-go
  version: release-3.9
1 The package name should match the name of the directory containing the glide.yaml file.

From a command prompt in the directory containing main.go and glide.yaml, run glide install --strip-vendor to download the OpenShift Origin client library and its dependencies.

From the same prompt, ensure that you are able to connect to OpenShift Origin using the oc client and can list pods and builds (oc get pods,builds).

Finally, run the code sample (go run main.go). It should list the same pods and builds that the oc client did.

Package Locations

The OpenShift Origin client library holds type definitions and client objects in multiple separate packages. Import paths to these packages, as well as suggested package names, follow.

Kubernetes type definitions

import (
        metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)
import (
        admissionregistrationv1beta1 "k8s.io/api/admissionregistration/v1beta1"
        admissionv1beta1 "k8s.io/api/admission/v1beta1"
        appsv1beta1 "k8s.io/api/apps/v1beta1"
        appsv1beta2 "k8s.io/api/apps/v1beta2"
        appsv1 "k8s.io/api/apps/v1"
        authenticationv1beta1 "k8s.io/api/authentication/v1beta1"
        authenticationv1 "k8s.io/api/authentication/v1"
        authorizationv1beta1 "k8s.io/api/authorization/v1beta1"
        authorizationv1 "k8s.io/api/authorization/v1"
        autoscalingv1 "k8s.io/api/autoscaling/v1"
        batchv1beta1 "k8s.io/api/batch/v1beta1"
        batchv1 "k8s.io/api/batch/v1"
        certificatesv1beta1 "k8s.io/api/certificates/v1beta1"
        corev1 "k8s.io/api/core/v1"
        eventsv1beta1 "k8s.io/api/events/v1beta1"
        extensionsv1beta1 "k8s.io/api/extensions/v1beta1"
        networkingv1 "k8s.io/api/networking/v1"
        policyv1beta1 "k8s.io/api/policy/v1beta1"
        rbacv1beta1 "k8s.io/api/rbac/v1beta1"
        rbacv1 "k8s.io/api/rbac/v1"
        storagev1beta1 "k8s.io/api/storage/v1beta1"
        storagev1 "k8s.io/api/storage/v1"
)

OpenShift type definitions

import (
        appsv1 "github.com/openshift/api/apps/v1"
        authorizationv1 "github.com/openshift/api/authorization/v1"
        buildv1 "github.com/openshift/api/build/v1"
        imagev1 "github.com/openshift/api/image/v1"
        networkv1 "github.com/openshift/api/network/v1"
        oauthv1 "github.com/openshift/api/oauth/v1"
        projectv1 "github.com/openshift/api/project/v1"
        quotav1 "github.com/openshift/api/quota/v1"
        routev1 "github.com/openshift/api/route/v1"
        securityv1 "github.com/openshift/api/security/v1"
        templatev1 "github.com/openshift/api/template/v1"
        userv1 "github.com/openshift/api/user/v1"
)

Kubernetes client objects

import (
        admissionregistrationv1beta1client "k8s.io/client-go/kubernetes/typed/admissionregistration/v1beta1"
        appsv1beta1client "k8s.io/client-go/kubernetes/typed/apps/v1beta1"
        appsv1beta2client "k8s.io/client-go/kubernetes/typed/apps/v1beta2"
        appsv1client "k8s.io/client-go/kubernetes/typed/apps/v1"
        authenticationv1beta1client "k8s.io/client-go/kubernetes/typed/authentication/v1beta1"
        authenticationv1client "k8s.io/client-go/kubernetes/typed/authentication/v1"
        authorizationv1beta1client "k8s.io/client-go/kubernetes/typed/authorization/v1beta1"
        authorizationv1client "k8s.io/client-go/kubernetes/typed/authorization/v1"
        autoscalingv1client "k8s.io/client-go/kubernetes/typed/autoscaling/v1"
        autoscalingv2beta1client "k8s.io/client-go/kubernetes/typed/autoscaling/v2beta1"
        batchv1beta1client "k8s.io/client-go/kubernetes/typed/batch/v1beta1"
        batchv1client "k8s.io/client-go/kubernetes/typed/batch/v1"
        certificatesv1beta1client "k8s.io/client-go/kubernetes/typed/certificates/v1beta1"
        corev1client "k8s.io/client-go/kubernetes/typed/core/v1"
        eventsv1beta1client "k8s.io/client-go/kubernetes/typed/events/v1beta1"
        extensionsv1beta1client "k8s.io/client-go/kubernetes/typed/extensions/v1beta1"
        networkingv1client "k8s.io/client-go/kubernetes/typed/networking/v1"
        policyv1beta1client "k8s.io/client-go/kubernetes/typed/policy/v1beta1"
        rbacv1beta1client "k8s.io/client-go/kubernetes/typed/rbac/v1beta1"
        rbacv1client "k8s.io/client-go/kubernetes/typed/rbac/v1"
        storagev1beta1client "k8s.io/client-go/kubernetes/typed/storage/v1beta1"
        storagev1client "k8s.io/client-go/kubernetes/typed/storage/v1"
)

OpenShift client objects

import (
        appsv1client "github.com/openshift/client-go/apps/clientset/versioned/typed/apps/v1"
        authorizationv1client "github.com/openshift/client-go/authorization/clientset/versioned/typed/authorization/v1"
        buildv1client "github.com/openshift/client-go/build/clientset/versioned/typed/build/v1"
        imagev1client "github.com/openshift/client-go/image/clientset/versioned/typed/image/v1"
        networkv1client "github.com/openshift/client-go/network/clientset/versioned/typed/network/v1"
        oauthv1client "github.com/openshift/client-go/oauth/clientset/versioned/typed/oauth/v1"
        projectv1client "github.com/openshift/client-go/project/clientset/versioned/typed/project/v1"
        quotav1client "github.com/openshift/client-go/quota/clientset/versioned/typed/quota/v1"
        routev1client "github.com/openshift/client-go/route/clientset/versioned/typed/route/v1"
        securityv1client "github.com/openshift/client-go/security/clientset/versioned/typed/security/v1"
        templatev1client "github.com/openshift/client-go/template/clientset/versioned/typed/template/v1"
        userv1client "github.com/openshift/client-go/user/clientset/versioned/typed/user/v1"
)