f5xc

README

f5xc

A limited F5 Distributed Cloud client library for Go based on published API documentation.

This is not a product created or supported by F5 Inc.

Documentation

Overview

Package f5xc implements a custom http.Client and helper functions to retrieve data from F5 Distributed Cloud endpoints.

Index

• Constants
• Variables
• func EnvelopeAPICall[T EnvelopeAllowed](client *http.Client, req *http.Request) (*T, error)
• func NewClient(options ...Option) (*http.Client, error)
• type Envelope
• type EnvelopeAllowed
• type LabelSelectorType
• type MatcherType
• type Metadata
• type Option
  • func WithAPIEndpoint(apiEndpoint string) Option
  • func WithAuthToken(token string) Option
  • func WithCACert(caCert string) Option
  • func WithCertKeyPair(certPath, keyPath string) Option
  • func WithP12Certificate(path, passphrase string) Option
• type PublicKey
  • func GetPublicKey(ctx context.Context, client *http.Client, version *int) (*PublicKey, error)
• type SecretPolicyDocument
  • func GetSecretPolicyDocument(ctx context.Context, client *http.Client, name, namespace string) (*SecretPolicyDocument, error)
• type SecretPolicyInfo
• type SecretPolicyRule

Constants

const PublicKeyURL = "/api/secret_management/get_public_key"

The partial URL to fetch a PublicKey from F5 Distributed Cloud.

const SecretPolicyDocumentURL = "/api/secret_management/namespaces/%s/secret_policys/%s/get_policy_document"

The partial URL to fetch PolicyDocument from F5 Distributed Cloud.

Variables

var (
	// Failed to add CA certificate to pool.
	ErrFailedToAppendCACert = errors.New("failed to append CA cert to CA pool")
	// Could not create a new custom http.Client because authentication was not provided.
	ErrMissingAuthentication = errors.New("a client certificate or API token must be provided")
	// Endpoint URL could not be parsed from the string provided, or the schema was invalid.
	ErrInvalidEndpointURL = errors.New("failed to parse API endpoint URL")
	// Endpoint URL was not provided to NewClient.
	ErrMissingURL = errors.New("an API URL must be provided")
	// Authentication via client certificate or API Token is not present in the request.
	ErrUnauthorized = errors.New("authentication is required")
	// Authorization failed and the client does not have permission to reach the endpoint.
	ErrForbidden = errors.New("access to endpoint is denied")
	// Returned by EnvelopeAPICall function when response status is not 200, 401 or 403.
	ErrUnexpectedHTTPStatus = errors.New("endpoint returned an unexpected status code")
)

Functions

func EnvelopeAPICall

func EnvelopeAPICall[T EnvelopeAllowed](client *http.Client, req *http.Request) (*T, error)

Helper method to make F5XC API requests where the response is expected to be in an Envelope, returning the embedded resource or an error. This function expects an HTTP status code of 200 as the only indicator of success; it will return nil if HTTP status code is 404, or one of the f5xc package errors for all other statuses.

func NewClient

func NewClient(options ...Option) (*http.Client, error)

Creates a new HTTP client that is pre-configured to authenticate to F5 XC endpoints.

Types

type Envelope

type Envelope[T EnvelopeAllowed] struct {
	Data T `json:"data" yaml:"data"`
}

Many F5XC endpoints encapsulate the requested information in an envelope with a data field contains the requested resource.

type EnvelopeAllowed

type EnvelopeAllowed interface {
	PublicKey | SecretPolicyDocument
}

Defines a type constraint for resources known to be encapsulated in an Envelope when requested from F5XC endpoints.

type LabelSelectorType

type LabelSelectorType struct {
	Expressions []string `json:"expressions" yaml:"expressions"`
}

Represents a matcher that selects resources based on Metadata label expressions, similar to Kubernetes.

type MatcherType

type MatcherType struct {
	ExactValues  []string `json:"exact_values" yaml:"exactValues"`
	RegexValues  []string `json:"regex_values" yaml:"regexValues"`
	Transformers []string `json:"transformers" yaml:"transformers"`
}

Represents a matcher that is commonly used to apply a set of declarations to a set of resources that satisfy one of the requirements.

type Metadata

type Metadata struct {
	Name      string `json:"name,omitempty" yaml:"name,omitempty"`
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`
	Tenant    string `json:"tenant,omitempty" yaml:"tenant,omitempty"`
}

Represents the metadata associated with F5XC data types.

type Option

type Option func(*config) error

Defines a configuration setting function.

func WithAPIEndpoint

func WithAPIEndpoint(apiEndpoint string) Option

Use the supplied endpoint URL for all requests to F5 XC when calling NewClient.

func WithAuthToken

func WithAuthToken(token string) Option

Implements an option that sets client authentication to use the provided authentication token, disabling certificate based authentication.

func WithCACert

func WithCACert(caCert string) Option

Adds the x509 CA Certificate at the given path to the set CA certificates known to the system when calling NewClient.

func WithCertKeyPair

func WithCertKeyPair(certPath, keyPath string) Option

Implements an Option that sets Client authentication to use the x509 certificate and key pair, disabling token authentication.

func WithP12Certificate

func WithP12Certificate(path, passphrase string) Option

Implements an Option that sets Client authentication to use the provided PKCS#12 certificate, disabling token authentication.

type PublicKey

type PublicKey struct {
	KeyVersion           int    `json:"key_version" yaml:"keyVersion"`
	ModulusBase64        string `json:"modulus_base64" yaml:"modulusBase64"`
	PublicExponentBase64 string `json:"public_exponent_base64" yaml:"publicExponentBase64"`
	Tenant               string `json:"tenant" yaml:"tenant"`
}

Represents an F5XC Public Key for authenticated account, as described at https://docs.cloud.f5.com/docs/api/secret-management#operation/ves.io.schema.secret_management.CustomAPI.GetPublicKey.

func GetPublicKey

func GetPublicKey(ctx context.Context, client *http.Client, version *int) (*PublicKey, error)

Returns a PublicKey from the F5 Distributed Cloud API endpoint for Secrets Management, or an error.

type SecretPolicyDocument

type SecretPolicyDocument struct {
	*Metadata
	PolicyID   string           `json:"policy_id" yaml:"policyId"`
	PolicyInfo SecretPolicyInfo `json:"policy_info" yaml:"policyInfo"`
}

Represents the complete specification of a secret policy as described at https://docs.cloud.f5.com/docs/api/secret-management#operation/ves.io.schema.secret_management.CustomAPI.GetPolicyDocument.

func GetSecretPolicyDocument

func GetSecretPolicyDocument(ctx context.Context, client *http.Client, name, namespace string) (*SecretPolicyDocument, error)

Returns a SecretPolicyDocument from the F5 Distributed Cloud API endpoint for Secrets Management, or an error.

type SecretPolicyInfo

type SecretPolicyInfo struct {
	Algo  string             `json:"algo" yaml:"algo"`
	Rules []SecretPolicyRule `json:"rules" yaml:"rules"`
}

Represents the specifications of a secret policy as described at https://docs.cloud.f5.com/docs/api/secret-management#operation/ves.io.schema.secret_management.CustomAPI.GetPolicyDocument.

type SecretPolicyRule

type SecretPolicyRule struct {
	Action            string             `json:"action" yaml:"action"`
	ClientName        string             `json:"client_name,omitempty" yaml:"clientName,omitempty"`
	ClientNameMatcher *MatcherType       `json:"client_name_matcher,omitempty" yaml:"clientNameMatcher,omitempty"`
	ClientSelector    *LabelSelectorType `json:"client_selector,omitempty" yaml:"clientSelector,omitempty"`
}

Represents a single SecretPolicyRule as described at https://docs.cloud.f5.com/docs/api/secret-policy-rule.