Documentation ¶
Overview ¶
Package k8s implements a Kubernetes client.
import ( "context" "github.com/karlmutch/k8s" appsv1 "github.com/karlmutch/k8s/apis/apps/v1" ) func listDeployments(ctx context.Context) (*appsv1.DeploymentList, error) { c, err := k8s.NewInClusterClient() if err != nil { return nil, err } var deployments appsv1.DeploymentList if err := c.List(ctx, "my-namespace", &deployments); err != nil { return nil, err } return deployments, nil }
Index ¶
- Constants
- func Bool(b bool) *bool
- func Int(i int) *int
- func Int32(i int32) *int32
- func Register(apiGroup, apiVersion, name string, namespaced bool, r Resource)
- func RegisterList(apiGroup, apiVersion, name string, namespaced bool, l ResourceList)
- func String(s string) *string
- type APIError
- type AuthInfo
- type AuthProviderConfig
- type Client
- func (c *Client) Create(ctx context.Context, req Resource, options ...Option) error
- func (c *Client) Delete(ctx context.Context, req Resource, options ...Option) error
- func (c *Client) Get(ctx context.Context, namespace, name string, resp Resource, options ...Option) error
- func (c *Client) List(ctx context.Context, namespace string, resp ResourceList, options ...Option) error
- func (c *Client) Update(ctx context.Context, req Resource, options ...Option) error
- func (c *Client) Watch(ctx context.Context, namespace string, r Resource, options ...Option) (*Watcher, error)
- type Cluster
- type Config
- type Context
- type Discovery
- func (d *Discovery) APIGroup(ctx context.Context, name string) (*metav1.APIGroup, error)
- func (d *Discovery) APIGroups(ctx context.Context) (*metav1.APIGroupList, error)
- func (d *Discovery) APIResources(ctx context.Context, groupName, groupVersion string) (*metav1.APIResourceList, error)
- func (d *Discovery) Version(ctx context.Context) (*Version, error)
- type ExecConfig
- type ExecEnvVar
- type LabelSelector
- type NamedAuthInfo
- type NamedCluster
- type NamedContext
- type NamedExtension
- type Option
- func DeleteAtomic() Option
- func DeleteGracePeriod(d time.Duration) Option
- func DeletePropagationBackground() Option
- func DeletePropagationForeground() Option
- func DeletePropagationOrphan() Option
- func QueryParam(name, value string) Option
- func ResourceVersion(resourceVersion string) Option
- func Subresource(name string) Option
- func Timeout(d time.Duration) Option
- type Preferences
- type Resource
- type ResourceList
- type Version
- type Watcher
Constants ¶
const ( // Types for watch events. EventAdded = "ADDED" EventDeleted = "DELETED" EventModified = "MODIFIED" EventError = "ERROR" )
const ( // AllNamespaces is given to list and watch operations to signify that the code should // list or watch resources in all namespaces. AllNamespaces = allNamespaces )
Variables ¶
This section is empty.
Functions ¶
func Int32 ¶ added in v1.0.0
Int32 is a convenience for converting an int32 literal to a pointer to an int32.
func RegisterList ¶ added in v1.0.0
func RegisterList(apiGroup, apiVersion, name string, namespaced bool, l ResourceList)
Types ¶
type APIError ¶
type APIError struct { // The status object returned by the Kubernetes API, Status *metav1.Status // Status code returned by the HTTP request. // // NOTE: For some reason the value set in Status.Code // doesn't correspond to the HTTP status code. Possibly // a bug? Code int }
APIError is an error from a unexpected status code.
type AuthInfo ¶
type AuthInfo struct { // ClientCertificate is the path to a client cert file for TLS. // +optional ClientCertificate string `json:"client-certificate,omitempty" yaml:"client-certificate,omitempty"` // ClientCertificateData contains PEM-encoded data from a client cert file for TLS. Overrides ClientCertificate // +optional ClientCertificateData []byte `json:"client-certificate-data,omitempty" yaml:"client-certificate-data,omitempty"` // ClientKey is the path to a client key file for TLS. // +optional ClientKey string `json:"client-key,omitempty" yaml:"client-key,omitempty"` // ClientKeyData contains PEM-encoded data from a client key file for TLS. Overrides ClientKey // +optional ClientKeyData []byte `json:"client-key-data,omitempty" yaml:"client-key-data,omitempty"` // Token is the bearer token for authentication to the kubernetes cluster. // +optional Token string `json:"token,omitempty" yaml:"token,omitempty"` // TokenFile is a pointer to a file that contains a bearer token (as described above). If both Token and TokenFile are present, Token takes precedence. // +optional TokenFile string `json:"tokenFile,omitempty" yaml:"tokenFile,omitempty"` // Impersonate is the username to imperonate. The name matches the flag. // +optional Impersonate string `json:"as,omitempty" yaml:"as,omitempty"` // Username is the username for basic authentication to the kubernetes cluster. // +optional Username string `json:"username,omitempty" yaml:"username,omitempty"` // Password is the password for basic authentication to the kubernetes cluster. // +optional Password string `json:"password,omitempty" yaml:"password,omitempty"` // AuthProvider specifies a custom authentication plugin for the kubernetes cluster. // +optional AuthProvider *AuthProviderConfig `json:"auth-provider,omitempty" yaml:"auth-provider,omitempty"` // Exec specifies a custom exec-based authentication plugin for the kubernetes cluster. // +optional Exec *ExecConfig `json:"exec,omitempty"` // Extensions holds additional information. This is useful for extenders so that reads and writes don't clobber unknown fields // +optional Extensions []NamedExtension `json:"extensions,omitempty" yaml:"extensions,omitempty"` }
AuthInfo contains information that describes identity information. This is use to tell the kubernetes cluster who you are.
type AuthProviderConfig ¶
type AuthProviderConfig struct { Name string `json:"name" yaml:"name"` Config map[string]string `json:"config" yaml:"config"` }
AuthProviderConfig holds the configuration for a specified auth provider.
type Client ¶
type Client struct { // The URL of the API server. Endpoint string // Namespace is the name fo the default reconciled from the client's config. // It is set when constructing a client using NewClient(), and defaults to // the value "default". // // This value should be used to access the client's default namespace. For // example, to create a configmap in the default namespace, use client.Namespace // when to fill the ObjectMeta: // // client, err := k8s.NewClient(config) // if err != nil { // // handle error // } // cm := v1.ConfigMap{ // Metadata: &metav1.ObjectMeta{ // Name: &k8s.String("my-configmap"), // Namespace: &client.Namespace, // }, // Data: map[string]string{"foo": "bar", "spam": "eggs"}, // } // err := client.Create(ctx, cm) // Namespace string // SetHeaders provides a hook for modifying the HTTP headers of all requests. // // client, err := k8s.NewClient(config) // if err != nil { // // handle error // } // client.SetHeaders = func(h http.Header) error { // h.Set("Authorization", "Bearer "+mytoken) // return nil // } // SetHeaders func(h http.Header) error Client *http.Client }
Client is a Kuberntes client.
func NewInClusterClient ¶
NewInClusterClient returns a client that uses the service account bearer token mounted into Kubernetes pods.
func (*Client) Create ¶ added in v1.0.0
Create creates a resource of a registered type. The API version and resource type is determined by the type of the req argument. The result is unmarshaled into req.
configMap := corev1.ConfigMap{ Metadata: &metav1.ObjectMeta{ Name: k8s.String("my-configmap"), Namespace: k8s.String("my-namespace"), }, Data: map[string]string{ "my-key": "my-val", }, } if err := client.Create(ctx, &configMap); err != nil { // handle error } // resource is updated with response of create request fmt.Println(configMap.Metadata.GetCreationTimestamp())
func (*Client) Watch ¶ added in v1.0.0
func (c *Client) Watch(ctx context.Context, namespace string, r Resource, options ...Option) (*Watcher, error)
Watch creates a watch on a resource. It takes an example Resource to determine what endpoint to watch.
Watch does not automatically reconnect. If a watch fails, a new watch must be initialized.
// Watch configmaps in the "kube-system" namespace var configMap corev1.ConfigMap watcher, err := client.Watch(ctx, "kube-system", &configMap) if err != nil { // handle error } defer watcher.Close() // Always close the returned watcher. for { cm := new(corev1.ConfigMap) eventType, err := watcher.Next(cm) if err != nil { // watcher encountered and error, exit or create a new watcher } fmt.Println(eventType, *cm.Metadata.Name) }
type Cluster ¶
type Cluster struct { // Server is the address of the kubernetes cluster (https://hostname:port). Server string `json:"server" yaml:"server"` // APIVersion is the preferred api version for communicating with the kubernetes cluster (v1, v2, etc). // +optional APIVersion string `json:"api-version,omitempty" yaml:"api-version,omitempty"` // InsecureSkipTLSVerify skips the validity check for the server's certificate. This will make your HTTPS connections insecure. // +optional InsecureSkipTLSVerify bool `json:"insecure-skip-tls-verify,omitempty" yaml:"insecure-skip-tls-verify,omitempty"` // CertificateAuthority is the path to a cert file for the certificate authority. // +optional CertificateAuthority string `json:"certificate-authority,omitempty" yaml:"certificate-authority,omitempty"` // CertificateAuthorityData contains PEM-encoded certificate authority certificates. Overrides CertificateAuthority // +optional CertificateAuthorityData []byte `json:"certificate-authority-data,omitempty" yaml:"certificate-authority-data,omitempty"` // Extensions holds additional information. This is useful for extenders so that reads and writes don't clobber unknown fields // +optional Extensions []NamedExtension `json:"extensions,omitempty" yaml:"extensions,omitempty"` }
Cluster contains information about how to communicate with a kubernetes cluster
type Config ¶
type Config struct { // Legacy field from pkg/api/types.go TypeMeta. // TODO(jlowdermilk): remove this after eliminating downstream dependencies. // +optional Kind string `json:"kind,omitempty" yaml:"kind,omitempty"` // DEPRECATED: APIVersion is the preferred api version for communicating with the kubernetes cluster (v1, v2, etc). // Because a cluster can run multiple API groups and potentially multiple versions of each, it no longer makes sense to specify // a single value for the cluster version. // This field isn't really needed anyway, so we are deprecating it without replacement. // It will be ignored if it is present. // +optional APIVersion string `json:"apiVersion,omitempty" yaml:"apiVersion,omitempty"` // Preferences holds general information to be use for cli interactions Preferences Preferences `json:"preferences" yaml:"preferences"` // Clusters is a map of referencable names to cluster configs Clusters []NamedCluster `json:"clusters" yaml:"clusters"` // AuthInfos is a map of referencable names to user configs AuthInfos []NamedAuthInfo `json:"users" yaml:"users"` // Contexts is a map of referencable names to context configs Contexts []NamedContext `json:"contexts" yaml:"contexts"` // CurrentContext is the name of the context that you would like to use by default CurrentContext string `json:"current-context" yaml:"current-context"` // Extensions holds additional information. This is useful for extenders so that reads and writes don't clobber unknown fields // +optional Extensions []NamedExtension `json:"extensions,omitempty" yaml:"extensions,omitempty"` }
Config holds the information needed to build connect to remote kubernetes clusters as a given user
type Context ¶
type Context struct { // Cluster is the name of the cluster for this context Cluster string `json:"cluster" yaml:"cluster"` // AuthInfo is the name of the authInfo for this context AuthInfo string `json:"user" yaml:"user"` // Namespace is the default namespace to use on unspecified requests // +optional Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"` // Extensions holds additional information. This is useful for extenders so that reads and writes don't clobber unknown fields // +optional Extensions []NamedExtension `json:"extensions,omitempty" yaml:"extensions,omitempty"` }
Context is a tuple of references to a cluster (how do I communicate with a kubernetes cluster), a user (how do I identify myself), and a namespace (what subset of resources do I want to work with)
type Discovery ¶
type Discovery struct {
// contains filtered or unexported fields
}
Discovery is a client used to determine the API version and supported resources of the server.
func NewDiscoveryClient ¶ added in v1.0.0
func (*Discovery) APIResources ¶
type ExecConfig ¶ added in v1.2.1
type ExecConfig struct { // Command to execute. Command string `json:"command"` // Arguments to pass to the command when executing it. // +optional Args []string `json:"args"` // Env defines additional environment variables to expose to the process. These // are unioned with the host's environment, as well as variables client-go uses // to pass argument to the plugin. // +optional Env []ExecEnvVar `json:"env"` // Preferred input version of the ExecInfo. The returned ExecCredentials MUST use // the same encoding version as the input. APIVersion string `json:"apiVersion,omitempty"` }
ExecConfig specifies a command to provide client credentials. The command is exec'd and outputs structured stdout holding credentials.
See the client.authentiction.k8s.io API group for specifications of the exact input and output format
type ExecEnvVar ¶ added in v1.2.1
ExecEnvVar is used for setting environment variables when executing an exec-based credential plugin.
type LabelSelector ¶
type LabelSelector struct {
// contains filtered or unexported fields
}
LabelSelector represents a Kubernetes label selector.
Any values that don't conform to Kubernetes label value restrictions will be silently dropped.
l := new(k8s.LabelSelector) l.Eq("component", "frontend") l.In("type", "prod", "staging")
func (*LabelSelector) Eq ¶
func (l *LabelSelector) Eq(key, val string)
Eq selects labels which have the key and the key has the provide value.
func (*LabelSelector) In ¶
func (l *LabelSelector) In(key string, vals ...string)
In selects labels which have the key and the key has one of the provided values.
func (*LabelSelector) NotEq ¶
func (l *LabelSelector) NotEq(key, val string)
NotEq selects labels where the key is present and has a different value than the value provided.
func (*LabelSelector) NotIn ¶
func (l *LabelSelector) NotIn(key string, vals ...string)
NotIn selects labels which have the key and the key is not one of the provided values.
func (*LabelSelector) Selector ¶
func (l *LabelSelector) Selector() Option
func (*LabelSelector) String ¶ added in v1.0.0
func (l *LabelSelector) String() string
type NamedAuthInfo ¶
type NamedAuthInfo struct { // Name is the nickname for this AuthInfo Name string `json:"name" yaml:"name"` // AuthInfo holds the auth information AuthInfo AuthInfo `json:"user" yaml:"user"` }
NamedAuthInfo relates nicknames to auth information
type NamedCluster ¶
type NamedCluster struct { // Name is the nickname for this Cluster Name string `json:"name" yaml:"name"` // Cluster holds the cluster information Cluster Cluster `json:"cluster" yaml:"cluster"` }
NamedCluster relates nicknames to cluster information
type NamedContext ¶
type NamedContext struct { // Name is the nickname for this Context Name string `json:"name" yaml:"name"` // Context holds the context information Context Context `json:"context" yaml:"context"` }
NamedContext relates nicknames to context information
type NamedExtension ¶
type NamedExtension struct { // Name is the nickname for this Extension Name string `json:"name" yaml:"name"` // Extension holds the extension information Extension runtime.RawExtension `json:"extension" yaml:"extension"` }
NamedExtension relates nicknames to extension information
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option represents optional call parameters, such as label selectors.
func DeleteAtomic ¶ added in v1.2.0
func DeleteAtomic() Option
func DeleteGracePeriod ¶ added in v1.2.0
func DeletePropagationBackground ¶ added in v1.2.0
func DeletePropagationBackground() Option
DeletePropagationBackground deletes the resources and causes the garbage collector to delete dependent resources in the background.
func DeletePropagationForeground ¶ added in v1.2.0
func DeletePropagationForeground() Option
DeletePropagationForeground deletes the resources and causes the garbage collector to delete dependent resources and wait for all dependents whose ownerReference.blockOwnerDeletion=true. API sever will put the "foregroundDeletion" finalizer on the object, and sets its deletionTimestamp. This policy is cascading, i.e., the dependents will be deleted with Foreground.
func DeletePropagationOrphan ¶ added in v1.2.0
func DeletePropagationOrphan() Option
DeletePropagationOrphan orphans the dependent resources during a delete.
func QueryParam ¶ added in v1.0.0
QueryParam can be used to manually set a URL query parameter by name.
func ResourceVersion ¶
ResourceVersion causes watch operations to only show changes since a particular version of a resource.
func Subresource ¶ added in v1.1.0
Subresource is a way to interact with a part of an API object without needing permissions on the entire resource. For example, a node isn't able to modify a pod object, but can update the "pods/status" subresource.
Common subresources are "status" and "scale".
type Preferences ¶
type Preferences struct { // +optional Colors bool `json:"colors,omitempty" yaml:"colors,omitempty"` // Extensions holds additional information. This is useful for extenders so that reads and writes don't clobber unknown fields // +optional Extensions []NamedExtension `json:"extensions,omitempty" yaml:"extensions,omitempty"` }
type Resource ¶ added in v1.0.0
type Resource interface {
GetMetadata() *metav1.ObjectMeta
}
Resource is a Kubernetes resource, such as a Node or Pod.
type ResourceList ¶ added in v1.0.0
Resource is list of common Kubernetes resources, such as a NodeList or PodList.
type Version ¶
type Version struct { Major string `json:"major"` Minor string `json:"minor"` GitVersion string `json:"gitVersion"` GitCommit string `json:"gitCommit"` GitTreeState string `json:"gitTreeState"` BuildDate string `json:"buildDate"` GoVersion string `json:"goVersion"` Compiler string `json:"compiler"` Platform string `json:"platform"` }
type Watcher ¶ added in v1.0.0
type Watcher struct {
// contains filtered or unexported fields
}
Watcher receives a stream of events tracking a particular resource within a namespace or across all namespaces.
Watcher does not automatically reconnect. If a watch fails, a new watch must be initialized.