core

Documentation

Overview

Package core contains parts of metroctl which do significant amounts of work beyond just providing a CLI for them. This package is intended to be used for integrating with functions provided by metroctl, for example for using them in integration tests or writing other frontends providing functionality similar to metroctl (like a GUI or webapp).

Index

• Constants
• Variables
• func DialNode(ctx context.Context, opkey ed25519.PrivateKey, ocert, ca *x509.Certificate, ...) (*grpc.ClientConn, error)
• func DialOpts(ctx context.Context, c *ConnectOptions) ([]grpc.DialOption, error)
• func GetClusterCA(path string) (cert *x509.Certificate, err error)
• func GetClusterCAWithTOFU(ctx context.Context, c *ConnectOptions) (*x509.Certificate, error)
• func GetNodes(ctx context.Context, mgmt api.ManagementClient, fexp string) ([]*api.Node, error)
• func GetOrMakeOwnerKey(path string) (ed25519.PrivateKey, error)
• func GetOwnerCredentials(path string) (cert *x509.Certificate, key ed25519.PrivateKey, err error)
• func GetOwnerKey(path string) (ed25519.PrivateKey, error)
• func GetOwnerTLSCredentials(path string) (*tls.Certificate, error)
• func InstallKubeletConfig(ctx context.Context, metroctlPath string, opts *ConnectOptions, ...) error
• func MakeInstallerImage(args MakeInstallerImageArgs) error
• func WriteCACertificate(path string, der []byte) error
• func WriteOwnerCertificate(path string, cert []byte) error
• func WriteOwnerKey(path string, priv ed25519.PrivateKey) error
• type CertificateTOFU
• type ConnectOptions
  • func (c *ConnectOptions) Dial(network, addr string) (net.Conn, error)
  • func (c *ConnectOptions) ProxyURL() string
  • func (c *ConnectOptions) ToFlags() []string
• type MakeInstallerImageArgs
• type TerminalTOFU
  • func (i *TerminalTOFU) Ask(ctx context.Context, connection *ConnectOptions, cert *x509.Certificate) (bool, error)

Constants

const (
	// OwnerKeyFileName is the filename of the owner key in a metroctl config
	// directory.
	OwnerKeyFileName = "owner-key.pem"
	// OwnerCertificateFileName is the filename of the owner certificate in a
	// metroctl config directory.
	OwnerCertificateFileName = "owner.pem"
	// CACertificateFileName is the filename of the cluster CA certificate in a
	// metroctl config directory.
	CACertificateFileName = "ca.pem"
)

Variables

var (
	// ErrNoCredentials indicates that the requested datum (eg. owner key or owner
	// certificate) is not present in the requested directory.
	ErrNoCredentials = errors.New("owner certificate or key does not exist")

	ErrNoCACertificate = errors.New("no cluster CA certificate while secure connection was requested")
)

Functions

func DialNode

func DialNode(ctx context.Context, opkey ed25519.PrivateKey, ocert, ca *x509.Certificate, proxyAddr, nodeId, nodeAddr string) (*grpc.ClientConn, error)

func DialOpts

func DialOpts(ctx context.Context, c *ConnectOptions) ([]grpc.DialOption, error)

func GetClusterCA

func GetClusterCA(path string) (cert *x509.Certificate, err error)

GetClusterCA returns the saved cluster CA certificate at the given metoctl configuration path. This does not perform TOFU if the certificate is not present.

func GetClusterCAWithTOFU

func GetClusterCAWithTOFU(ctx context.Context, c *ConnectOptions) (*x509.Certificate, error)

GetClusterCAWithTOFU returns the CA certificate of the cluster, performing trust-on-first-use (TOFU) checks per ConnectOptions first if necessary.

If no locally persisted CA is found, this will connect to the cluster and retrieve it. Then, if now owner certificate is present, a TOFU prompt will be shown to the user. Otherwise, the retrieved CA will be verified against the local owner certificate.

If the above logic accepts the CA it will be written to the configuration directory and used automatically on subsequent connections.

An error will be returned if the user rejects the certificate as part of the TOFU process, if the returned CA does not matched persisted owner certificate (if available) or if retrieving the certificate from the cluster fails for some other reason.

func GetNodes

func GetNodes(ctx context.Context, mgmt api.ManagementClient, fexp string) ([]*api.Node, error)

GetNodes retrieves node records, filtered by the supplied node filter expression fexp.

func GetOrMakeOwnerKey

func GetOrMakeOwnerKey(path string) (ed25519.PrivateKey, error)

GetOrMakeOwnerKey returns the owner key for a given metroctl configuration directory path, generating and saving it first if it doesn't exist.

func GetOwnerCredentials

func GetOwnerCredentials(path string) (cert *x509.Certificate, key ed25519.PrivateKey, err error)

GetOwnerCredentials loads and returns a raw ED25519 private key alongside a DER-encoded X509 certificate from the saved owner key and certificate in a given metroctl configuration directory path. If either the key or certificate doesn't exist, ErrNoCredentials will be returned.

func GetOwnerKey

func GetOwnerKey(path string) (ed25519.PrivateKey, error)

GetOwnerKey loads and returns a raw ED25519 private key from the saved owner key in a given metroctl configuration directory path. If the owner key doesn't exist, ErrNoCredentials will be returned.

func GetOwnerTLSCredentials

func GetOwnerTLSCredentials(path string) (*tls.Certificate, error)

GetOwnerTLSCredentials returns a client TLS Certificate for authenticating to the metropolis cluster, based on metroctl configuration at a given path.

func InstallKubeletConfig

func InstallKubeletConfig(ctx context.Context, metroctlPath string, opts *ConnectOptions, configName, server string) error

InstallKubeletConfig modifies the default kubelet kubeconfig of the host system to be able to connect via a metroctl (and an associated ConnectOptions) to a Kubernetes apiserver at IP address/hostname 'server'.

The kubelet's kubeconfig changes will be limited to contexts/configs/... named configName. The configName context will be made the default context only if there is no other default context in the current subconfig.

Kubeconfigs can only take a single Kubernetes server address, so this function similarly only allows you to specify only a single server address.

func MakeInstallerImage

func MakeInstallerImage(args MakeInstallerImageArgs) error

MakeInstallerImage generates an installer disk image containing a Table partition table and a single FAT32 partition with an installer and optionally with a bundle and/or Node Parameters.

func WriteCACertificate

func WriteCACertificate(path string, der []byte) error

WriteCACertificate writes the given der-encoded X509 certificate to the given metorctl configuration directory path.

func WriteOwnerCertificate

func WriteOwnerCertificate(path string, cert []byte) error

WriteOwnerCertificate saves a given DER-encoded X509 certificate as the owner key for a given metroctl configuration directory path.

func WriteOwnerKey

func WriteOwnerKey(path string, priv ed25519.PrivateKey) error

WriteOwnerKey saves a given raw ED25519 private key as the owner key at a given metroctl configuration directory path.

Types

type CertificateTOFU

type CertificateTOFU interface {
	// Ask is called whenever the user needs to confirm some certificate as being the
	// CA certificate presented as the result of connection via given ConnectOptions.
	// If true is returned, the certificate is accepted and persisted as the
	// canonical CA certificate of the cluster pointed to by ConnectOptions.
	Ask(ctx context.Context, connection *ConnectOptions, cert *x509.Certificate) (bool, error)
}

CertificateTOFU is an interface to different providers of a user interaction to confirm the validity of a CA certificate.

type ConnectOptions

type ConnectOptions struct {
	// ConfigPath is the path at which the metroctl configuration/credentials live.
	// If not set, the default will be used.
	ConfigPath string
	// ProxyServer is a host:port pair that indicates the metropolis cluster should
	// be reached via the given SOCKS5 proxy. If not set, the cluster can be reached
	// directly from the host networking stack.
	ProxyServer string
	// Endpoints are the IP addresses/hostnames (without port part) of the Metropolis
	// instances that metroctl should use to establish connectivity to a cluster.
	// These instances should have the ControlPlane role set.
	Endpoints []string
	// ResolverLogger can be set to enable verbose logging of the Metropolis RPC
	// resolver layer.
	ResolverLogger logging.Leveled
	// TOFU overrides the trust-on-first-use behaviour for CA certificates for the
	// connection. If not set, TerminalTOFU is used which will interactively ask the
	// user to accept a CA certificate using os.Stdin/Stdout.
	TOFU CertificateTOFU
}

ConnectOptions define how to reach a Metropolis cluster from metroctl.

This structure can be built directly. All unset fields mean 'default'. It can then be used to generate the equivalent flags to passs to metroctl.

Nil pointers to ConnectOptions are equivalent to an empty ConneectOptions when methods on it are called.

func (*ConnectOptions) Dial

func (c *ConnectOptions) Dial(network, addr string) (net.Conn, error)

func (*ConnectOptions) ProxyURL

func (c *ConnectOptions) ProxyURL() string

ProxyURL returns a kubeconfig-compatible URL of the proxy server configured by ConnectOptions, or an empty string if not set.

func (*ConnectOptions) ToFlags

func (c *ConnectOptions) ToFlags() []string

ToFlags returns the metroctl flags corresponding to the options described by this ConnectionOptions struct.

type MakeInstallerImageArgs

type MakeInstallerImageArgs struct {
	// Path to either a file or a disk which will contain the installer data.
	TargetPath string

	// Reader for the installer EFI executable. Mandatory.
	Installer fat32.SizedReader

	// Optional NodeParameters to be embedded for use by the installer.
	NodeParams *api.NodeParameters

	// Optional Reader for a Metropolis bundle for use by the installer.
	Bundle fat32.SizedReader
}

type TerminalTOFU

type TerminalTOFU struct {
	// Out will be used to output prompts to the user. If not set, defaults to
	// os.Stdout.
	Out io.Writer
	// In will be used to read responses from the user. If not set, defaults to
	// os.Stdin.
	In io.Reader
}

TerminalTOFU implements CertificateTOFU in an interactive way, similar to SSH.

func (*TerminalTOFU) Ask

func (i *TerminalTOFU) Ask(ctx context.Context, connection *ConnectOptions, cert *x509.Certificate) (bool, error)