Documentation
¶
Overview ¶
Package ansibleinv translates an Ansible inventory into the Cluster document cargoship installs from. Ansible resolves the inventory -- group membership, group_vars, host_vars, dynamic inventory plugins, and everything else its own precedence rules cover -- and hands the result here already merged. Nothing in this package parses an inventory file, because reproducing those rules in Go would reproduce them wrongly.
Ansible supplies the inventory; it does not connect to the fleet. The translated document goes to cargoship's own phase pipeline, which opens every SSH connection itself from the management node.
Index ¶
Constants ¶
const ( VarBastion = Prefix + "bastion" VarEnvironment = Prefix + "environment" VarFiles = Prefix + "files" VarHost = Prefix + "host" VarHostname = Prefix + "hostname" VarNodeLabels = Prefix + "node_labels" VarNodeTaints = Prefix + "node_taints" VarPrivateAddress = Prefix + "private_address" VarPrivateInterface = Prefix + "private_interface" VarProfile = Prefix + "profile" VarProfileSpec = Prefix + "profile_spec" )
The variables cargoship reads out of the Ansible namespace.
const ( VarAnsibleHost = "ansible_host" VarAnsiblePort = "ansible_port" VarAnsibleUser = "ansible_user" VarAnsibleKeyFile = "ansible_ssh_private_key_file" )
The Ansible connection variables cargoship reads. Everything else under ansible_ is ignored: there are hundreds of them, they belong to Ansible's own connection plugins, and cargoship does not connect the way Ansible does.
const Prefix = "cargoship_"
Prefix is the namespace for the host variables that configure cargoship. A variable under it that this package does not know is an error rather than a value ignored, because a misspelled variable is indistinguishable from an unset one at install time.
Variables ¶
This section is empty.
Functions ¶
func DefaultRoleGroups ¶
DefaultRoleGroups maps each cargoship role onto an Ansible group of the same name. It names cargoship's own roles rather than guessing at an Ansible convention, because there is no one convention to guess at: an inventory may call its control plane `control_plane`, `masters`, `etcd`, or anything else. An operator whose groups are named otherwise says so.
func Translate ¶
func Translate(in Input, meta ClusterMeta) (*cluster.Cluster, error)
Translate builds a Cluster from a resolved Ansible inventory.
Host order in the result is load-bearing: ConfigureEngine makes the first controller the leader, so the leader is the first host of the first group listed under RoleGroups ["controller"]. Controllers come before workers, and within a role the groups are walked in the order RoleGroups lists them, each group's hosts in Ansible's inventory order.
The result is checked against the embedded inventory schema before it is returned, so a translation mistake is reported as the field it landed in rather than as a phase failing against a live host some minutes into an apply.
Types ¶
type ClusterMeta ¶
type ClusterMeta struct {
// Name sets metadata.name, which cargoship uses as the kubeconfig context name.
Name string `json:"name"`
// LoadBalancer is the hostname clients use to reach the control plane.
LoadBalancer string `json:"loadbalancer"`
// Profiles maps a profile name to the host and engine overrides a host can select.
Profiles map[string]cluster.Profiles `json:"profiles,omitempty"`
// Registries lists the container registries the cluster uses.
Registries []cluster.Registries `json:"registries,omitempty"`
// Values overrides the values the distro package was built with.
Values map[string]any `json:"values,omitempty"`
}
ClusterMeta is everything the generated document needs that no host carries: the parts of a Cluster that describe the cluster rather than a node.
type HostVars ¶ added in v0.41.0
type HostVars struct {
// Address cargoship opens the SSH connection to. Defaults to the name the inventory knows the host by, which is the common shape.
AnsibleHost string `json:"ansible_host,omitempty"`
// Port cargoship connects on. Defaults to 22.
AnsiblePort int `json:"ansible_port,omitempty" jsonschema:"oneof_type=string;integer"`
// User cargoship connects as. Defaults to root.
AnsibleUser string `json:"ansible_user,omitempty"`
// Path to the SSH private key cargoship authenticates with.
AnsibleKeyFile string `json:"ansible_ssh_private_key_file,omitempty"`
// Jump host cargoship reaches this node through. Cargoship does not parse ansible_ssh_common_args, so an inventory that reaches the fleet through a bastion for Ansible's own sake has to say so again here.
Bastion *ssh.Config `json:"cargoship_bastion,omitempty"`
// Shell environment cargoship sets on the host, as a map of variable name to value.
Environment map[string]string `json:"cargoship_environment,omitempty"`
// Each entry is a file cargoship uploads to the host: src is a path on the management node, dst the path on the node.
Files []cluster.Files `json:"cargoship_files,omitempty"`
// Ports cargoship opens on this node, and the firewall rules it applies there.
Host cluster.HostConfig `json:"cargoship_host,omitempty"`
// What the node calls itself, when that is not the name the inventory knows it by. Defaults to the inventory hostname.
Hostname string `json:"cargoship_hostname,omitempty"`
// Kubernetes node labels applied to this node. A host setting this replaces its group's rather than adding to it.
NodeLabels map[string]string `json:"cargoship_node_labels,omitempty"`
// Kubernetes node taints applied to this node. A host setting this replaces its group's rather than adding to it.
NodeTaints []string `json:"cargoship_node_taints,omitempty"`
// Address the cluster uses between nodes, when it is not the one cargoship would discover. A node with two interfaces is the usual reason.
PrivateAddress string `json:"cargoship_private_address,omitempty"`
// Interface the cluster uses between nodes, when it is not the one cargoship would discover.
PrivateInterface string `json:"cargoship_private_interface,omitempty"`
// Name of the profile this host selects. Defaults to the host's role, which is what makes the node-role.kubernetes.io/<profile> label say something.
Profile string `json:"cargoship_profile,omitempty"`
// Body of the profile this host selects, declared beside the selection. A profile defined twice with different bodies is an error naming both sources.
ProfileSpec *cluster.Profiles `json:"cargoship_profile_spec,omitempty"`
}
HostVars is the set of Ansible variables cargoship reads for one host, as a type, so that a JSON Schema can be generated from it and an editor can complete and check a host_vars or group_vars file.
Nothing decodes into it. hostFromVars reads the variables one at a time, because it reports a wrong type as the variable that carries it rather than as a path into a document, and that is the error an operator can act on. This type exists for the schema and for the test that pins it to `known` -- it is a description of the same thing, kept honest by TestHostVarsCoverKnownVariables rather than by being the thing itself.
The field types are the real ones, so `cargoship_host` completes as a HostConfig and `cargoship_profile_spec` as a Profiles, out of the same $defs the cluster schema publishes.
ansible_port is the one field whose Go type is narrower than what is accepted, and the oneof_type tag on it is not decoration. portVar takes a number or a string, because an INI inventory gives every variable as a string and a YAML one gives a number, and both are ordinary ways to write an inventory -- so the schema has to permit both or it would flag a working file. The int here is what portVar returns, not a claim about what it reads.
The port inside cargoship_bastion is deliberately not the same. That variable is decoded whole into rig's ssh.Config, whose Port is an int with no such leniency, so a quoted "22" there fails the decode with `cannot unmarshal string into Go struct field .port of type int`. The schema says integer for it and string-or-integer for ansible_port, which is the asymmetry the code actually has rather than a tidier one.
func (HostVars) JSONSchemaExtend ¶ added in v0.41.0
func (HostVars) JSONSchemaExtend(s *jsonschema.Schema)
JSONSchemaExtend makes the generated schema describe a real host_vars file rather than a document cargoship owns.
Two things have to be true at once, and neither is the generator's default. A host_vars file carries variables for every role in the play, so an unknown key cannot be an error -- the default `additionalProperties: false` would flag every line that is not ours. But a misspelled `cargoship_profil` has to be an error, because Ansible has no notion of a variable belonging to anyone and a misspelled variable is indistinguishable from an unset one until install time.
The negative lookahead says exactly that: a key under the cargoship_ prefix that is not one of the names below matches, and matching a `false` schema is a rejection. Everything else falls through to additionalProperties and is allowed. The lookahead is honoured by yaml-language-server, which compiles these patterns with JavaScript's own RegExp -- verified against the real server rather than assumed, because a pattern it could not compile would fail open and silently check nothing.
type Input ¶
type Input struct {
// Groups maps an Ansible group name to the hosts in it, in inventory order.
Groups map[string][]string `json:"groups"`
// HostVars maps an inventory hostname to the variables Ansible resolved for it.
HostVars map[string]map[string]any `json:"hostvars"`
// RoleGroups maps a cargoship role to the Ansible groups whose hosts take that role.
RoleGroups map[string][]string `json:"roleGroups"`
}
Input is the inventory as Ansible resolved it. Groups and HostVars are Ansible's own `groups` and `hostvars`, projected by the action plugin; RoleGroups is the operator's mapping from a cargoship role onto the Ansible groups that carry it.
type Request ¶
type Request struct {
Input
// Cluster holds the settings that belong to the cluster rather than to any host.
Cluster ClusterMeta `json:"cluster"`
}
Request is one complete translation: the inventory Ansible resolved, plus the cluster-wide settings an inventory has no way to carry. It is what the action plugin sends and what `cargoship inventory from-ansible` reads, so the same document that reproduces a translation by hand is the one a playbook produced.