Initial draft for Airship 2.0 airshipctl command line client
Change-Id: I61820f6dfd70b4f26f47f9c9af50c9be4bf2da0a
This commit is contained in:
Rodolfo Pacheco
Rodolfo Pacheco
parent
c5064ef2eb
commit
41e68fe4a4
Binary file not shown.
Binary file not shown.
|
After Width: | Height: | Size: 265 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 106 KiB |
|
|
@ -0,0 +1,370 @@
|
|||
..
|
||||
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||
License.
|
||||
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
|
||||
single: AirshipCTL
|
||||
single: Command Line
|
||||
|
||||
====================================================
|
||||
Airship CTL - Airship 2.0 Command Line Interface
|
||||
====================================================
|
||||
|
||||
Pegleg is responsible for shepherding deployment manifest documents from their
|
||||
resting places in Git repositories to a consumable format that is ready
|
||||
for ingestion into Airship. This spec expands its responsibility to
|
||||
account for secure generation and encryption of secrets that are
|
||||
required within an Airship-based deployment.
|
||||
|
||||
Links
|
||||
=====
|
||||
|
||||
The work to author and implement this spec will be tracked under this
|
||||
`Jira Feature`_.
|
||||
|
||||
Problem description
|
||||
===================
|
||||
|
||||
The mail goal for Airship 2.0 is to :
|
||||
- Allow for smaller deployments by introducing an Ephemeral CAirship control plane
|
||||
- Further the adoption of entrenched projects
|
||||
- Continue vanishing complexity
|
||||
|
||||
A big part of achieving this goal is moving complexity out of sites , abig poaert of achieving the goals for Airship 2.0 is teh inception of a new component called teh airshipctl.
|
||||
This spec defines what this component needs to support.
|
||||
|
||||
|
||||
Impacted components
|
||||
===================
|
||||
|
||||
The existing Airship components are not direct;y impacted by teh CTL, however some of the functionality introduced via the CTL will replace or abstract or encapsulate the purpose of existign tools.
|
||||
|
||||
#. Pegleg: Will become a plugin behind teh AirshipCTL
|
||||
#. Deckhand: Functionality such as Document Revision will now be achieved via an Airship CTL Plugin.
|
||||
|
||||
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
AIRSHIPCTL Architecture
|
||||
-----------------------
|
||||
|
||||
The heart of the Airship 2.0 platform is the airshipctl command line interface. It places an emphasis on
|
||||
a thick client that is effectively able to speak to k8s in remote sites and natively understands argo workflows
|
||||
to drive cluster life cycle management. This is contrast to Airship 1.0 which leveraged a Shipyard API in the remote site,
|
||||
which was a long-lived service. The goals for this pivot are to reduce the underlying infrastructure required to support
|
||||
updates to an existing site and reduce the number of Airship specific YAML documents required to produce and manage a site,
|
||||
vastly simplifying the overall design.
|
||||
|
||||
This utility is a net-new go module that produces two binaries: airshipctl and airshipui.
|
||||
Both of these utilities operate on a kubernetes cluster security context, and understand how to interpret and generate a
|
||||
skeleton Airship document set. The airshipctl utility is the main entrypoint for bootstrapping a cluster, collecting and
|
||||
pushing documents, and managing workflows.
|
||||
|
||||
All functionality provided by the AirshipCtl will support a Framework for supported plugins. Every ffeature provided by teh AirshipCTL
|
||||
will need to be supported by providing explicit plugins.
|
||||
|
||||
|
||||
Framework
|
||||
---------
|
||||
Define and create the framework for the go plugin that will produce airshipctl.
|
||||
This includes defining the plugin framework to ensure it is extensible, logging, vendoring, and basic CI/CD so the project can gain momentum.
|
||||
The goal is that all known initial subcommands, e.g. bootstrap, document, and so on will be plugins themselves, ensuring it supports extensibility day one.
|
||||
|
||||
Specifically the framework needs to define :
|
||||
- Well defined mechanism to cionsume and use plugins
|
||||
- Guidlines on expectations from plugins
|
||||
- Transactional information : Mechanism to identify a request initiated by teh AirshipCTL , that allows for correlation between CTL and UI, and/or logging.
|
||||
|
||||
|
||||
Security Context
|
||||
----------------
|
||||
Both the CLI and the UI will need to be able to leverage a standard k8s security context for interacting with remote sites.
|
||||
It should also understand Airship site contexts so that it can be pointed at a local document set and work with that during subsequent commands without needing
|
||||
to be fed the same document set with every command similar to interacting with the same Kubernetes cluster throughout a kubectl session.
|
||||
|
||||
The initial proposed list of commands that will be implemented is defined below :
|
||||
|
||||
Config
|
||||
------
|
||||
|
||||
Modify airshipctl configuration files using subcommands like "airshipctl config set current-context my-context"
|
||||
In general this commands allows us to modify teh configuration of airchipctl in a ssimilar fashion as kubectl context management
|
||||
|
||||
|
||||
The loading order follows these rules:
|
||||
|
||||
If the --airshipconfig flag is set, then only that file is loaded. The flag may only be set once and no merging takes place.
|
||||
If $AIRSHIPCONFIG environment variable is set, then it is used as a list of paths (normal path delimiting rules for your system). These paths are merged. When a value is modified, it is modified in the file that defines the stanza. When a value is created, it is created in the first file that exists. If no files in the chain exist, then it creates the last file in the list.
|
||||
Otherwise, ${HOME}/.airship/config is used and no merging takes place.
|
||||
|
||||
Like kubectl it should support
|
||||
|
||||
|
||||
- ``airshipctl *config current-context*``
|
||||
- ``airshipctl *config delete-context*``
|
||||
- ``airshipctl *config get-contexts*``
|
||||
- ``airshipctl *config set-context*``
|
||||
- ``airshipctl *config use-context*``
|
||||
|
||||
|
||||
|
||||
|
||||
Boostrap
|
||||
---------
|
||||
|
||||
The bootstrap plugin will drive the lifecycle required to :
|
||||
- stand up a bootsrap cluster if one doesn;t existing
|
||||
- initialize a target remote cluster, by configuring at least the initial server for that cluster
|
||||
- the plugin will leverage the intentions for the site provided by the yaml declarations, including BareMetalHost CR's.
|
||||
|
||||
|
||||
``airshipctl bootstrap -s *SiteName* -y *YamlLocation*``
|
||||
|
||||
.. note::
|
||||
*I think we dont need sitename as an argument, it can be impolicit by the setting of teh context, unless it refers to the label or structure of the documents only*
|
||||
|
||||
**FLAGS**
|
||||
|
||||
+----------+-----------+-----------+----------------------------+
|
||||
| NAME | SHORTHAND | DEFAULT | USAGE |
|
||||
+==========+===========+===========+============================+
|
||||
| sitename | s | | Sitename document label |
|
||||
+----------+-----------+-----------+----------------------------+
|
||||
| yaml | y | | Location of the yaml files |
|
||||
+----------+-----------+-----------+----------------------------+
|
||||
|
||||
The lifecycle driven by the bootstrap command is depicted by the flow in the image below :
|
||||
|
||||
.. image:: ../../images/airship_2_0_airshipcli_and_clusterctl.png
|
||||
:width: 600
|
||||
|
||||
The goal is for Airship bootstrap to function with metal3-io, azure, openstack, and the generic-ssh providers to support baremetal, cloud, openstack vms, and bring your own infrastructure use cases day one.
|
||||
|
||||
|
||||
Document
|
||||
--------
|
||||
Documents are the life-blood of Airship. Airship documents, which are a collection of metal3-io, machine, cluster-api, armada, and argo documents, need to be collected, pushed to sites, and validated.
|
||||
This plugin would be responsible for handling all of that client-side. Including document revisions,document as secrets, etc.
|
||||
The goal here is also that the document plugin--for flexibility--should support pushing a subset of document sets.
|
||||
For instance, much like we have update_site and deploy_site today, which basically indicate whether baremetal documents are submitted or not, the same should be true of Airship 2.0 but with more flexibility.
|
||||
Documents should be able to be assigned arbitrary meta classes or buckets, and you should be able to target a specific bucket to apply to a site if you do not wish to see all workflows evaluated for development
|
||||
or some other strategic purpose.
|
||||
|
||||
|
||||
- ``airshipctl document -s *SiteName* -y *YamlLocation*``
|
||||
|
||||
.. note::
|
||||
*I think we dont need sitename as an argument, it can be impolicit by the settin gof teh context, unless it refers to teh label or structure of teh documents only*
|
||||
|
||||
**FLAGS**
|
||||
|
||||
+----------+-----------+-----------+----------------------------+
|
||||
| NAME | SHORTHAND | DEFAULT | USAGE |
|
||||
+==========+===========+===========+============================+
|
||||
| sitename | s | | Sitename document label |
|
||||
+----------+-----------+-----------+----------------------------+
|
||||
| yaml | y | | Location of the yaml files |
|
||||
+----------+-----------+-----------+----------------------------+
|
||||
|
||||
**OPTIONS**
|
||||
|
||||
+----------+----------------------------------------------------+
|
||||
| NAME | USAGE |
|
||||
+==========+====================================================+
|
||||
| revision | Provides options to manage revision of manifests |
|
||||
+----------+----------------------------------------------------+
|
||||
| secret | Provides a mechanism to manage manifest as secret |
|
||||
+----------+----------------------------------------------------+
|
||||
| validate | Provides options for yaml validation |
|
||||
+----------+----------------------------------------------------+
|
||||
| init | Create a structure for the yaml documents |
|
||||
+----------+----------------------------------------------------+
|
||||
|
||||
|
||||
- ``airshipctl document -s *SiteName* -y *YamlLocation* **secret**``
|
||||
|
||||
Airshipctl will manage secrets locally and deliver them to the appropriate context
|
||||
Should be able situations where it csannot deliver the secret
|
||||
|
||||
.. note::
|
||||
*Should it care, should secrets be throw away / ephemeral on th side of airshipctl*
|
||||
|
||||
|
||||
**SECRET OPTIONS**
|
||||
|
||||
+----------+-----------+-------------------------------------------+
|
||||
| NAME | SHORTHAND | USAGE |
|
||||
+==========+===========+===========================================+
|
||||
| get | g | Get a specific secret |
|
||||
+----------+-----------+-------------------------------------------+
|
||||
| create | c | Create the secret from the manifest |
|
||||
+----------+-----------+-------------------------------------------+
|
||||
| list | l | list all secret for the specific manifest |
|
||||
+----------+-----------+-------------------------------------------+
|
||||
| *delete* | d | Delete a specific secret for the manifest |
|
||||
+----------+-----------+-------------------------------------------+
|
||||
|
||||
- ``airshipctl document -s *SiteName* -y *YamlLocation* **revision**``
|
||||
|
||||
.. note::
|
||||
*Was is a revision , is it a name that byu convention has some timestamp and version, where the name has a relationship to the secret document*
|
||||
|
||||
**REVISION FLAGS**
|
||||
|
||||
+----------+-----------+-----------+----------------------------+
|
||||
| NAME | SHORTHAND | DEFAULT | USAGE |
|
||||
+==========+===========+===========+============================+
|
||||
| name | n | | Revision name? label |
|
||||
+----------+-----------+-----------+----------------------------+
|
||||
|
||||
**REVISION OPTIONS**
|
||||
|
||||
+----------+-----------+---------------------------+
|
||||
| NAME | SHORTHAND | USAGE |
|
||||
+==========+===========+===========================+
|
||||
| get | g | Get a specific revision |
|
||||
+----------+-----------+---------------------------+
|
||||
| compare | d | Compare between revisions |
|
||||
+----------+-----------+---------------------------+
|
||||
| list | l | list all revisions |
|
||||
+----------+-----------+---------------------------+
|
||||
|
||||
|
||||
|
||||
- ``airshipctl document -s *SiteName* -y *YamlLocation* **validate**``
|
||||
|
||||
Airshipctl will manage secrets locally and deliver them to the appropriate context
|
||||
Should be able situations where it csannot deliver the secret
|
||||
|
||||
**VALIDATE OPTIONS**
|
||||
|
||||
+----------+-----------+---------------------------+
|
||||
| NAME | SHORTHAND | USAGE |
|
||||
+==========+===========+===========================+
|
||||
| lint | l | |
|
||||
+----------+-----------+---------------------------+
|
||||
| .... | .. | |
|
||||
+----------+-----------+---------------------------+
|
||||
|
||||
- ``airshipctl document -y *YamlLocation* **init**``
|
||||
|
||||
Initialize document structure and bootstrap contents. It creates a skeleton Airship document to allow new users to
|
||||
begin building the definition for a new site.
|
||||
|
||||
Executing this command will create the following directory structure
|
||||
|
||||
..<Yaml Target Directory>/
|
||||
global/
|
||||
software/
|
||||
charts/
|
||||
|
||||
config/
|
||||
|
||||
manifests/
|
||||
|
||||
secrets/
|
||||
|
||||
passphrases/
|
||||
|
||||
publickey/
|
||||
|
||||
site/
|
||||
baremetal/
|
||||
|
||||
baremetalhosts/
|
||||
|
||||
machines/
|
||||
|
||||
|
||||
|
||||
.. note::
|
||||
*More detail as to what files or CRs can be automatically generated in order to be used as templates, or simple because the information in them is generic*
|
||||
|
||||
|
||||
|
||||
Cluster
|
||||
-------
|
||||
|
||||
The CLI should support integration with a cluster-registry.
|
||||
Much of the same information is available in a cluster-api generated Cluster CRD that a cluster registry
|
||||
should be populated with. The communities themselves are looking to align on this and we should ensure
|
||||
airshipctl supports the ultimate path.
|
||||
|
||||
- ``airshipctl document -s *SiteName* -y *YamlLocation* **cluster**``
|
||||
|
||||
|
||||
**CLUSTER OPTIONS**
|
||||
|
||||
+----------+-----------+--------------------------------------------------------+
|
||||
| NAME | SHORTHAND | USAGE |
|
||||
+==========+===========+========================================================+
|
||||
| status | s | |
|
||||
+----------+-----------+--------------------------------------------------------+
|
||||
| state | t | State of the site, CRD and their verions. Argo version | |
|
||||
+----------+-----------+--------------------------------------------------------+
|
||||
|
||||
|
||||
.. note::
|
||||
*Cluster might not be the best name for this, could be named site instead *
|
||||
|
||||
|
||||
Workflow
|
||||
--------
|
||||
|
||||
|
||||
- ``airshipctl workflow -s *SiteName* -y *YamlLocation*``
|
||||
|
||||
**WORKFLOW OPTIONS**
|
||||
|
||||
+--------------+-----------+---------------------------+
|
||||
| NAME | SHORTHAND | USAGE |
|
||||
+==============+===========+===========================+
|
||||
| sitemanage | m | |
|
||||
+--------------+-----------+---------------------------+
|
||||
| redeployhost | h | |
|
||||
+--------------+-----------+---------------------------+
|
||||
|
||||
|
||||
The definition of a site state is a collection of yaml . This work flows will be responsible for effecting the state depicted by this yaml. Whether this is a 1st time deployment , an expansion or simple software stack configuration changes. This workflow will be responsible for deliver and executing the intentions described by the YAML.
|
||||
|
||||
- ``airshipctl workflow -s *SiteName* -y *YamlLocation* **sitemanage**``
|
||||
|
||||
**SITEMANAGE OPTIONS**
|
||||
|
||||
+----------+-----------+---------------------------+
|
||||
| NAME | SHORTHAND | USAGE |
|
||||
+==========+===========+===========================+
|
||||
| .. | .. | |
|
||||
+----------+-----------+---------------------------+
|
||||
|
||||
|
||||
This workflow essentially will encapsulate the logic required to prepare and post configure a host after redeployment. In essence a host should be redeployable by simple altering the BareMetalHost specification and the associated MachineSpec definition. The reason for a specific workflow, is that there could be tasks to be performed in preparation of the redeploy, and after the redeploy occurs.
|
||||
|
||||
- ``airshipctl workflow -s *SiteName* -y *YamlLocation* **redeployhost**``
|
||||
|
||||
**SITEMANAGEREDEPLOYHOST OPTIONS**
|
||||
|
||||
+----------+-----------+---------------------------+
|
||||
| NAME | SHORTHAND | USAGE |
|
||||
+==========+===========+===========================+
|
||||
| host | | |
|
||||
+----------+-----------+---------------------------+
|
||||
|
||||
|
||||
Implementation
|
||||
==============
|
||||
.. image:: ../../images/airshipctl.png
|
||||
:width: 600
|
||||
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
|
||||
|
||||
References
|
||||
==========
|
||||
|
||||
.
|
||||
Loading…
Reference in New Issue