diagnostics

Documentation

Index

• type AffectedObject
• type ClientDiagnostic
• type ConfigDiff
• type ConfigDump
• type ConfigDumpResponse
• type DiffIndex
• type DiffResponse
• type DumpMeta
• type EntityDiff
  • func NewEntityDiff(diff string, action string, entity diff.Entity) EntityDiff
• type FallbackAffectedObjectMeta
• type FallbackResponse
• type FallbackStatus
• type Server
  • func NewServer(logger logr.Logger, cfg ServerConfig) Server
  • func (s *Server) ConfigDumps() ClientDiagnostic
  • func (s *Server) Listen(ctx context.Context, port int) error
• type ServerConfig

Types

type AffectedObject

type AffectedObject struct {
	// UID is the unique identifier of the object.
	UID k8stypes.UID

	// Group is the object's group.
	Group string
	// Kind is the object's Kind.
	Kind string
	// Namespace is the object's Namespace.
	Namespace string
	// Name is the object's Name.
	Name string
}

AffectedObject is a Kubernetes object associated with diagnostic information.

type ClientDiagnostic

type ClientDiagnostic struct {
	// DumpsIncludeSensitive is true if the configuration dump includes sensitive values, such as certificate private
	// keys and credential secrets.
	DumpsIncludeSensitive bool

	// Configs is the channel that receives configuration blobs from the configuration update strategy implementation.
	Configs chan ConfigDump

	// FallbackCacheMetadata is the channel that receives fallback metadata from the fallback cache generator.
	FallbackCacheMetadata chan fallback.GeneratedCacheMetadata

	// Diffs is the channel that receives diff info in DB mode.
	Diffs chan ConfigDiff
}

ClientDiagnostic contains settings and channels for receiving diagnostic data from the controller's Kong client.

type ConfigDiff

type ConfigDiff struct {
	Hash      string       `json:"hash"`
	Entities  []EntityDiff `json:"entities"`
	Timestamp string       `json:"timestamp"`
}

ConfigDiff holds a config update, including its config hash, the rough timestamp when the controller completed sending it to the gateway, and the entities that changed in the course of reconciling the config state.

type ConfigDump

type ConfigDump struct {
	// Config is the configuration KIC applied or attempted to apply.
	Config file.Content
	// Meta contains information about the status and context of the configuration dump.
	Meta DumpMeta
	// RawResponseBody is the raw Kong Admin API response body from a config apply. It is only available in DB-less mode.
	RawResponseBody []byte
}

ConfigDump contains a config dump and a flag indicating that the config was not successfully applid.

type ConfigDumpResponse

type ConfigDumpResponse struct {
	ConfigHash string       `json:"hash"`
	Config     file.Content `json:"config"`
}

ConfigDumpResponse is the GET /debug/config/[successful|failed] response schema.

type DiffIndex

type DiffIndex struct {
	// ConfigHash is the config hash for the associated diff.
	ConfigHash string `json:"hash"`
	Timestamp  string `json:"timestamp"`
}

DiffIndex maps a hash to its timestamp.

type DiffResponse

type DiffResponse struct {
	// Message provides explanatory information, if any.
	Message string `json:"message,omitempty"`
	// ConfigHash is the config hash for the associated diffs.
	ConfigHash string `json:"hash"`
	// Timestamp is the time this diff was received by the diff server. This is roughly the time the sync operation
	// completed. May be a second or so after the last gateway API call, since it's taken when KIC finishes processing
	// GDR events.
	Timestamp string `json:"timestamp"`
	// Diffs are the diffs for modified objects.
	Diffs []EntityDiff `json:"diffs"`
	// Available lists the currently available diff hashes and timestamps.
	Available []DiffIndex `json:"available"`
}

DiffResponse is the GET /debug/config/diff response schema.

type DumpMeta

type DumpMeta struct {
	// Failed indicates the dump was not accepted by the Kong admin API.
	Failed bool
	// Fallback indicates that the dump is a fallback configuration attempted after a failed config update.
	Fallback bool
	// Hash is the configuration hash.
	Hash string
}

DumpMeta annotates a config dump.

type EntityDiff

type EntityDiff struct {
	Generated generatedEntity `json:"kongEntity"`
	Action    string          `json:"action"`
	Diff      string          `json:"diff,omitempty"`
}

EntityDiff is an individual entity change. It includes the entity metadata, the action performed during reconciliation, and the diff string for update actions.

func NewEntityDiff

func NewEntityDiff(diff string, action string, entity diff.Entity) EntityDiff

NewEntityDiff creates a diagnostic entity diff.

type FallbackAffectedObjectMeta

type FallbackAffectedObjectMeta struct {
	// Group is the resource group.
	Group string `json:"group"`
	// Kind is the resource kind.
	Kind string `json:"kind"`
	// Version is the resource version.
	Version string `json:"version,omitempty"`
	// Namespace is the object namespace.
	Namespace string `json:"namespace"`
	// Namespace is the object name.
	Name string `json:"name"`
	// ID is the object UID.
	ID string `json:"id"`
	// CausingObjects is the object that triggered this
	CausingObjects []string `json:"causingObjects,omitempty"`
}

FallbackAffectedObjectMeta is a fallback affected object metadata.

type FallbackResponse

type FallbackResponse struct {
	// Status is the fallback configuration generation status.
	Status FallbackStatus `json:"status"`
	// BrokenObjects is the list of objects that are broken.
	BrokenObjects []FallbackAffectedObjectMeta `json:"brokenObjects,omitempty"`
	// ExcludedObjects is the list of objects that were excluded from the fallback configuration.
	ExcludedObjects []FallbackAffectedObjectMeta `json:"excludedObjects,omitempty"`
	// BackfilledObjects is the list of objects that were backfilled from the last valid cache state.
	BackfilledObjects []FallbackAffectedObjectMeta `json:"backfilledObjects,omitempty"`
}

FallbackResponse is the GET /debug/config/fallback response schema.

type FallbackStatus

type FallbackStatus string

FallbackStatus describes whether the fallback configuration generation was triggered or not. Making this a string type not a bool to allow for potential future expansion of the status.

const (
	// FallbackStatusTriggered indicates that the fallback configuration generation was triggered.
	FallbackStatusTriggered FallbackStatus = "triggered"

	// FallbackStatusNotTriggered indicates that the fallback configuration generation was not triggered.
	FallbackStatusNotTriggered FallbackStatus = "not-triggered"
)

type Server

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

Server is an HTTP server running exposing the pprof profiling tool, and processing diagnostic dumps of Kong configurations.

func NewServer

func NewServer(logger logr.Logger, cfg ServerConfig) Server

NewServer creates a diagnostics server ready to start listening.

func (*Server) ConfigDumps

func (s *Server) ConfigDumps() ClientDiagnostic

ConfigDumps returns an object allowing dumping succeeded and failed configuration updates. It will return a zero value of the type in case the config dumps are not enabled.

func (*Server) Listen

func (s *Server) Listen(ctx context.Context, port int) error

Listen starts up the HTTP server and blocks until ctx expires.

type ServerConfig

type ServerConfig struct {
	// ProfilingEnabled enables profiling endpoints.
	ProfilingEnabled bool

	// ConfigDumpsEnabled enables config dumps endpoints.
	ConfigDumpsEnabled bool

	// DumpSensitiveConfig makes config dumps to include sensitive information.
	DumpSensitiveConfig bool
}

ServerConfig contains configuration for the diagnostics server.