furyagent

furyagent documentation

furyagent is the right agent for your Kubernetes Fury Cluster. It will help you create and maintain your cluster certificates, manage access to nodes and many more.

Source Code

You can find the source code in its own github repository.

Version

Latest stable furyagent release is v0.2.0.

Install

You can install furyagent binary in any Linux/macOS based system.

Github Releases

Every furyagent release is published as GitHub release in the form of a binary file and a (.tar.gz) archive.

To install it in any Linux/macOS based system:

$ uname
Darwin
$ curl -Ls https://github.com/sighupio/furyagent/releases/download/v0.2.0/furyagent-darwin-amd64 -o furyagent
$ chmod +x furyagent
$ mv furyagent /usr/local/bin/furyagent
$ furyagent version
Furyagent version 0.2.0 - md5: 7fece81e18c245da0b2744214c2af751 - /usr/local/bin/furyagent

Homebrew

If you are a macOS user (it also works in Linux), you should be familiar with Homebrew. To install furyagent using Homebrew follow this simple guide:

$ brew tap sighupio/furyagent
$ brew install furyagent
$ furyagent version
Furyagent version 0.2.0 - md5: 7fece81e18c245da0b2744214c2af751 - /usr/local/bin/furyagent

Usage

$ furyagent --help
A command line tool to manage cluster deployment with kubernetes

Usage:
  furyagent [command]

Available Commands:
  backup        Executes backups
  configure     Executes configuration
  help          Help about any command
  init          Executes initialization, uploads ca files
  parsed-config Prints the parsed furyagent.yaml file
  restore       Executes restores
  version       Prints the client version information

Flags:
      --config furyagent.yaml   config file (default is furyagent.yaml) (default "furyagent.yml")
  -h, --help                    help for furyagent

Use "furyagent [command] --help" for more information about a command.

Configuration

furyagent.yml is a yaml file where is specified the cluster configuration

structure:

storage: # furyagent will store all stuff here
  provider:  # provider identificator: possible values: s3|azure|google|local. each provider has its own configuration parameters.
  bucketName: # s3|azure|google provider. Required object storage bucket name
  url: # s3 provider. optional config value for changing s3 endpoint. Useful while using minio
  aws_access_key: # s3 provider. Required as it is one key of a pair of AWS credentials
  aws_secret_key: # s3 provider. Required as it is one key of a pair of AWS credentials.
  region: # s3 provider. Required as part of the authentication mechanism
  azure_storage_account: # azure provider. Required as it is one key of a pair of Azure credentials
  azure_storage_key: # azure provider. Required as it is one key of a pair of Azure credentials
  google_service_account: # google provider. Required as part of the authentication mechanism.
  google_project_id: # google provider. Required as part of the authentication mechanism.
  path: # local provider. Required as it is the location where to store everything generated with furyagent
clusterComponent: # Configuration of a cluster component
  nodeName: # Name of the node to be configured. Only used while doing etcd stuff
  etcd: # etcd configuration
    dataDir: # Directory where to store etcd data
    certDir: # Directory where to store etcd certificates
    caCertFilename: # Filename of the CA certificate
    caKeyFilename:  # Filename of the CA private key
    clientCertFilename: # Filename of the Client certificate
    clientKeyFilename: # Filename of the Client private key
    initialClusterToken: # Unique identificator of the cluster.
    snapshotFile: # Filename to store temporal snapshot file while running backup/restore etcd
    endpoint: # etcd reachable endpoint
  master: # master configuration
    certDir: # Directory where to store master certificates
    caCertFilename: # Filename of the CA certificate
    caKeyFilename: # Filename of the CA private key
    saPubFilename: # Filename of the ServiceAccount public key
    saKeyFilename: # Filename of the ServiceAccount private key
    proxyCaCertFilename: # Filename of the CA certificate of the proxy
    proxyKeyCertFilename: # Filename of the CA private key of the proxy
  node: # node configuration
    joinTimeout: # Timeout used until node join fails. In minutes. If not passed, default is 30 minutes.
  openvpn: # openvpn configuration
    certDir: # Directory where to store openvpn certificates
    servers: # List of VPN servers
  sshkeys: # Configuration of users with access to the cluster
    user: # Name of the system user to be created and added public keys from users
    tempDir: # Temporal directory where public keys will be downloaded before applying to the cluster
    localDirConfigs: # Where furyagent will look for ssh-users.yml file. It will find {localDirConfigs}/ssh-users.yml
    adapter: # Adapter configuration where to find user public keys
      name: # possible options: github|http
      uri: # Only required if clusterComponent.sshkeys.adapter.name is http. It should provide keys in the following format: {uri}/{user_id}.keys

ssh-users.yml structure:

users: # List of user with access to the cluster
  - name: # Name of the operator who has access to the cluster
    user_id: # user id in the sshKeys provider/adapter

Commands

init

The init command can be used to create and upload required files to create etcd nodes, master nodes, openvpn servers or upload a common ssh configuration for every instance.

$ furyagent init --help
Executes initialization, uploads ca files

Usage:
  furyagent init [command]

Available Commands:
  etcd        uploads etcd certificates to s3
  master      uploads master certificates to s3
  openvpn     uploads openvpn certificates to s3
  ssh-keys    upload ssh to s3

Flags:
  -d, --directory string   directory with files to be uploaded (default is .) (default ".")
  -h, --help               help for init

Global Flags:
      --config string   config file path (default "furyagent.yml")

Use "furyagent init [command] --help" for more information about a command.

init etcd

This command generates a ca (private key and cert) to be used by the etcd cluster. Once generated, furyagent will upload these files to the provider defined in furyagent.yml file under pki/etcd directory.

init master

This command generates a ca (private key and cert) to be used by the Kubernetes cluster (control-plan). It will generate other certificates required by other components of the Kubernetes control-plane). Once generated, furyagent will upload these files to the provider defined in furyagent.yml file under pki/master directory.

init openvpn

This command generates a ca (private key and cert) to be used by the openvpn servers. Once generated, It also generates server certificates and other openvpn related files like ta.key and crls files. furyagent will upload these files to the provider defined in furyagent.yml file under pki/vpn directory.

init ssh-keys

This command will upload the ssh-users.yml file containing the definition of all users allowed to operate the cluster. It will be available under ssh directory.

init result

If you run every init command you will end with the following files/structure:

storage-provider/
├── pki
│   ├── etcd
│   │   ├── ca.crt
│   │   └── ca.key
│   ├── master
│   │   ├── ca.crt
│   │   ├── ca.key
│   │   ├── front-proxy-ca.crt
│   │   ├── front-proxy-ca.key
│   │   ├── sa.key
│   │   └── sa.pub
│   └── vpn
│       ├── ca.crl
│       ├── ca.crt
│       ├── ca.key
│       ├── server.crt
│       ├── server.key
│       └── ta.key
└── ssh
    └── ssh-users.yml

configure

The configure command can be used to prepare (on each node) files to create etcd nodes, master nodes, openvpn servers or apply a common ssh configuration for every instance.

$ furyagent configure --help
Executes configuration

Usage:
  furyagent configure [command]

Available Commands:
  etcd           Configures etcd node
  master         Configures master node
  node           Get join.sh script from s3 and execute the join process
  openvpn        Get OpenVPN certificates from s3
  openvpn-client Create and revoke OpenVPN users
  ssh-keys       Setup ssh keys from s3

Flags:
  -h, --help        help for configure
      --overwrite   overwrite config files

Global Flags:
      --config string   config file path (default "furyagent.yml")

Use "furyagent configure [command] --help" for more information about a command.

configure etcd

This command downloads the ca (private key and cert) to beeing used by the etcd cluster in the correct directory. This command should run in an etcd node.

configure master

This command downloads all required files to create a Kubernetes Control plane. This command should run in every Kubernetes Master nodes.

configure node

This command downloads a script (uploaded by a master node) to let the node join the cluster. Once downloaded furyagent tries to execute it until reach the timeout defined in the furyagent.yml file (attribute: clusterComponent.node.joinTimeout).

configure openvpn

This command downloads every required file to prepare the creation of a vpn server. This command should run on every VPN Server.

configure openvpn-client

This command enables the ovpn profiles list, creation and revocation. You can create ovpn profiles using:

furyagent configure openvpn-client --client-name fury-operator-1 > fury-operator-1.ovpn

list available ovpn profiles as a table:

$ furyagent configure openvpn-client --list
+----------------+------------+------------+---------+--------------------------------+
|      USER      | VALID FROM |  VALID TO  | EXPIRED |            REVOKED             |
+----------------+------------+------------+---------+--------------------------------+
| luca.zecca     | 2020-03-19 | 2021-03-19 | false   | true 2020-03-19 14:47:40 +0000 |
|                |            |            |         | UTC                            |
+----------------+------------+------------+---------+--------------------------------+
| simone.messina | 2020-03-19 | 2021-03-19 | false   | false 0001-01-01 00:00:00      |
|                |            |            |         | +0000 UTC                      |
+----------------+------------+------------+---------+--------------------------------+

or in json format:

$ furyagent configure openvpn-client --list --output=json
[{"User":"luca.zecca","Valid_from":"2020-03-19","Valid_to":"2021-03-19","Expired":false,"Revoked":{"Revoked":true,"RevokeTime":"2020-03-19T14:47:40Z"}},{"User":"simone.messina","Valid_from":"2020-03-19","Valid_to":"2021-03-19","Expired":false,"Revoked":{"Revoked":false,"RevokeTime":"0001-01-01T00:00:00Z"}}]

If you want to revoke a client ovpn profile run:

furyagent configure openvpn-client --client-name fury-operator-1 --revoke

configure ssh-keys

This command will create/modify a system user to access every instance in the cluster. It downloads users public keys adding these to the .ssh/authorized_keys file of the system user defined in the furyagent.yml file.

This command should run on every instance part of the cluster, including VPN servers.

backup

The backup command can be used to backup etcd cluster data.

$ furyagent backup
Executes backups

Usage:
  furyagent backup [command]

Available Commands:
  etcd        Backups etcd node

Flags:
  -h, --help   help for backup

Global Flags:
      --config string   config file path (default "furyagent.yml")

Use "furyagent backup [command] --help" for more information about a command.

backup etcd

This command creates a snapshot of the current data available in the etcd cluster uploading the resulting file to the storage provider defined in the furyagent.yml file.

restore

The restore command can be used to restore etcd cluster data from an snapshot file.

Executes restores

Usage:
  furyagent restore [command]

Available Commands:
  etcd        Restores etcd node

Flags:
  -h, --help   help for restore

Global Flags:
      --config string   config file path (default "furyagent.yml")

Use "furyagent restore [command] --help" for more information about a command.

restore etcd

This command downloads the snapshot file defined in the furyagent.yml file restoring it in the etcd cluster.