kstatus

package module
v0.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 13, 2023 License: MIT Imports: 12 Imported by: 0

README

Low Dependency/Scalable Kubernetes Resource Status Check Library


This is a low dependency/scalable Kubernetes resource status check library that performs magic modifications based on kubernetes-sigs/cli-utils/kstatus.

📜 Language

English | 简体中文

✨ Core Feature

  • ⚡ Low Dependency
  • 🌲 Scalable

⚙️ Usage

go get github.com/elliotxx/kstatus

📖 Example

package main

import (
	"github.com/elliotxx/kstatus"
)

func main() {
    // deployment := getDeploymentFromCluster()
    
    res, err := Compute(deployment)
    if err != nil {
        panic(err)
    }
    fmt.Println(toJSON(res))
}

Output:

{
    "type": "Reconciling",
    "status": "True",
    "reason": "LessUpdated",
    "message": "Updated: 0/1"
}

More examples: ./example_test.go

Documentation

Overview

Package kstatus contains functionality for computing the status of Kubernetes resources.

The statuses defined in this package are:

  • InProgress
  • Current
  • Failed
  • Terminating
  • NotFound
  • Unknown

Computing the status of a resources can be done by calling the Compute function in the status package. 

import (
  "github.com/elliotxx/kstatus"
)

res, err := kstatus.Compute(resource)

The package also defines a set of new conditions:

  • InProgress
  • Failed

These conditions have been chosen to follow the "abnormal-true" pattern where conditions should be set to true for error/abnormal conditions and the absence of a condition means things are normal.

Index

Constants

View Source 
const (
	TooFewReady     = "LessReady"
	TooFewAvailable = "LessAvailable"
	TooFewUpdated   = "LessUpdated"
	TooFewReplicas  = "LessReplicas"
	ExtraPods       = "ExtraPods"

	OnDeleteUpdateStrategy = "OnDelete"

	// How long a pod can be unscheduled before it is reported as
	// unschedulable.
	ScheduleWindow = 15 * time.Second
)
View Source 
const (
	// The set of standard conditions defined in this package. These follow the "abnormality-true"
	// convention where conditions should have a true value for abnormal/error situations and the absence
	// of a condition should be interpreted as a false value, i.e. everything is normal.
	ConditionStalled     ConditionType = "Stalled"
	ConditionReconciling ConditionType = "Reconciling"

	// The set of status conditions which can be assigned to resources.
	InProgressStatus  Status = "InProgress"
	FailedStatus      Status = "Failed"
	CurrentStatus     Status = "Current"
	TerminatingStatus Status = "Terminating"
	NotFoundStatus    Status = "NotFound"
	UnknownStatus     Status = "Unknown"
)

Variables

View Source 
var LegacyTypes = map[string]GetConditionsFn{
	"Service":                    ServiceConditions,
	"Pod":                        PodConditions,
	"Secret":                     AlwaysReady,
	"PersistentVolumeClaim":      PvcConditions,
	"apps/StatefulSet":           StsConditions,
	"apps/DaemonSet":             DaemonsetConditions,
	"extensions/DaemonSet":       DaemonsetConditions,
	"apps/Deployment":            DeploymentConditions,
	"extensions/Deployment":      DeploymentConditions,
	"apps/ReplicaSet":            ReplicasetConditions,
	"extensions/ReplicaSet":      ReplicasetConditions,
	"policy/PodDisruptionBudget": PdbConditions,
	"batch/CronJob":              AlwaysReady,
	"ConfigMap":                  AlwaysReady,
	"batch/Job":                  JobConditions,
	"apiextensions.k8s.io/CustomResourceDefinition": CRDConditions,
}

LegacyTypes defines the mapping from GroupKind to a function that can compute the status for the given resource.

View Source 
var Statuses = []Status{InProgressStatus, FailedStatus, CurrentStatus, TerminatingStatus, UnknownStatus}

Functions

func Augment 

func Augment(u *unstructured.Unstructured) error

Augment takes a resource and augments the resource with the standard status conditions.

func GetIntField 

func GetIntField(obj map[string]interface{}, fieldPath string, defaultValue int) int

GetIntField return field as string defaulting to value if not found

func GetStringField 

func GetStringField(obj map[string]interface{}, fieldPath string, defaultValue string) string

GetStringField return field as string defaulting to value if not found

func HasConditionWithStatus 

func HasConditionWithStatus(conditions []BasicCondition, conditionType string, status corev1.ConditionStatus) bool

func YamlToUnstructured 

func YamlToUnstructured(t *testing.T, yml string) *unstructured.Unstructured

Types

type BasicCondition 

type BasicCondition struct {
	// Type Condition type
	Type string `json:"type" yaml:"type"`
	// Status is one of True,False,Unknown
	Status corev1.ConditionStatus `json:"status" yaml:"status"`
	// Reason simple single word reason in CamleCase
	// +optional
	Reason string `json:"reason,omitempty" yaml:"reason"`
	// Message human readable reason
	// +optional
	Message string `json:"message,omitempty" yaml:"message"`
}

BasicCondition fields that are expected in a condition

func GetConditionWithStatus 

func GetConditionWithStatus(conditions []BasicCondition, conditionType string, status corev1.ConditionStatus) (BasicCondition, bool)

type Condition 

type Condition struct {
	// Type condition type
	Type ConditionType `json:"type,omitempty" yaml:"type,omitempty"`
	// Status String that describes the condition status
	Status corev1.ConditionStatus `json:"status,omitempty" yaml:"status,omitempty"`
	// Reason one work CamelCase reason
	Reason string `json:"reason,omitempty" yaml:"reason,omitempty"`
	// Message Human readable reason string
	Message string `json:"message,omitempty" yaml:"message,omitempty"`
}

Condition defines the general format for conditions on Kubernetes resources. In practice, each kubernetes resource defines their own format for conditions, but most (maybe all) follows this structure.

func NewReconcilingCondition 

func NewReconcilingCondition(reason, message string) Condition

NewReconcilingCondition creates an reconciling condition with the given reason and message.

func NewStalledCondition 

func NewStalledCondition(reason, message string) Condition

func (*Condition) String 

func (c *Condition) String() string

type ConditionStatus 

type ConditionStatus struct {
	// Array of Conditions as expected to be present in kubernetes resources
	Conditions []BasicCondition `json:"conditions" yaml:"conditions"`
}

ConditionStatus represent status with condition array

type ConditionType 

type ConditionType string

ConditionType defines the set of condition types allowed inside a Condition struct.

func (ConditionType) String 

func (c ConditionType) String() string

String returns the ConditionType as a string.

type GetConditionsFn 

type GetConditionsFn func(*unstructured.Unstructured) (*Result, error)

GetConditionsFn defines the signature for functions to compute the status of a built-in resource.

func GetLegacyConditionsFn 

func GetLegacyConditionsFn(u *unstructured.Unstructured) GetConditionsFn

GetLegacyConditionsFn returns a function that can compute the status for the given resource, or nil if the resource type is not known.

type ObjWithConditions 

type ObjWithConditions struct {
	// Status as expected to be present in most compliant kubernetes resources
	Status ConditionStatus `json:"status" yaml:"status"`
}

ObjWithConditions Represent meta object with status.condition array

func GetObjectWithConditions 

func GetObjectWithConditions(in map[string]interface{}) (*ObjWithConditions, error)

GetObjectWithConditions return typed object

type Result 

type Result struct {
	// Status
	Status Status `json:"status,omitempty" yaml:"status,omitempty"`
	// Message
	Message string `json:"message,omitempty" yaml:"message,omitempty"`
	// Conditions list of extracted conditions from Resource
	Conditions []Condition `json:"conditions,omitempty" yaml:"conditions,omitempty"`
}

Result contains the results of a call to compute the status of a resource.

func AlwaysReady 

func AlwaysReady(_ *unstructured.Unstructured) (*Result, error)

AlwaysReady Used for resources that are always ready

func CRDConditions 

func CRDConditions(u *unstructured.Unstructured) (*Result, error)

func CheckGenericProperties 

func CheckGenericProperties(u *unstructured.Unstructured) (*Result, error)

CheckGenericProperties looks at the properties that are available on all or most of the Kubernetes resources. If a decision can be made based on this information, there is no need to look at the resource-specidic rules. This also checks for the presence of the conditions defined in this package. If any of these are set on the resource, a decision is made solely based on this and none of the resource specific rules will be used. The goal here is that if controllers, built-in or custom, use these conditions, we can easily find status of resources.

func CheckReadyCondition 

func CheckReadyCondition(u *unstructured.Unstructured) (*Result, error)

CheckReadyCondition checks if a resource has a Ready condition, and if so, it will use the value of this condition to determine the status. There are a few challenges with this: - If a resource doesn't set the Ready condition until it is True, the library have no way of telling whether the resource is using the Ready condition, so it will fall back to the strategy for unknown resources, which is to assume they are always reconciled. - If the library sees the resource before the controller has had a chance to update the conditions, it also will not realize the resource use the Ready condition. - There is no way to determine if a resource with the Ready condition set to False is making progress or is doomed.

func Compute 

func Compute(u *unstructured.Unstructured) (*Result, error)

Compute finds the status of a given unstructured resource. It does not fetch the state of the resource from a cluster, so the provided unstructured must have the complete state, including status.

The returned result contains the status of the resource, which will be one of

  • InProgress
  • Current
  • Failed
  • Terminating

It also contains a message that provides more information on why the resource has the given status. Finally, the result also contains a list of standard resources that would belong on the given resource.

func DaemonsetConditions 

func DaemonsetConditions(u *unstructured.Unstructured) (*Result, error)

DaemonsetConditions return standardized Conditions for DaemonSet

func DeploymentConditions 

func DeploymentConditions(u *unstructured.Unstructured) (*Result, error)

DeploymentConditions return standardized Conditions for Deployment.

For Deployments, we look at .status.conditions as well as the other properties under .status. Status will be Failed if the progress deadline has been exceeded.

func JobConditions 

func JobConditions(u *unstructured.Unstructured) (*Result, error)

JobConditions return standardized Conditions for Job

A job will have the InProgress status until it starts running. Then it will have the Current status while the job is running and after it has been completed successfully. It will have the Failed status if it the job has failed.

func NewFailedStatus 

func NewFailedStatus(reason, message string) *Result

func NewInProgressStatus 

func NewInProgressStatus(reason, message string) *Result

NewInProgressStatus creates a status Result with the InProgress status and an InProgress condition.

func PdbConditions 

func PdbConditions(_ *unstructured.Unstructured) (*Result, error)

PdbConditions computes the status for PodDisruptionBudgets. A PDB is currently considered Current if the disruption controller has observed the latest version of the PDB resource and has computed the AllowedDisruptions. PDBs do have ObservedGeneration in the Status object, so if this function gets called we know that the controller has observed the latest changes. The disruption controller does not set any conditions if computing the AllowedDisruptions fails (and there are many ways it can fail), but there is PR against OSS Kubernetes to address this: https://github.com/kubernetes/kubernetes/pull/86929

func PodConditions 

func PodConditions(u *unstructured.Unstructured) (*Result, error)

PodConditions return standardized Conditions for Pod

func PvcConditions 

func PvcConditions(u *unstructured.Unstructured) (*Result, error)

PvcConditions return standardized Conditions for PVC

func ReplicasetConditions 

func ReplicasetConditions(u *unstructured.Unstructured) (*Result, error)

ReplicasetConditions return standardized Conditions for Replicaset

func ServiceConditions 

func ServiceConditions(u *unstructured.Unstructured) (*Result, error)

ServiceConditions return standardized Conditions for Service

func StsConditions 

func StsConditions(u *unstructured.Unstructured) (*Result, error)

StsConditions return standardized Conditions for Statefulset

StatefulSet does define the .status.conditions property, but the controller never actually sets any Conditions. Thus, status must be computed only based on the other properties under .status. We don't have any way to find out if a reconcile for a StatefulSet has failed.

func (*Result) String 

func (r *Result) String() string

type Status 

type Status string

Status defines the set of statuses a resource can have.

func FromStringOrDie 

func FromStringOrDie(text string) Status

StatusFromString turns a string into a Status. Will panic if the provided string is not a valid status.

func (Status) String 

func (s Status) String() string

String returns the status as a string.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.