Chapter 1 Introduction to the Platform CLI

The Oracle Linux Cloud Native Environment Platform Command-Line Interface, olcnectl, is used to configure, deploy and manage the components of Oracle Linux Cloud Native Environment. The olcnectl command is installed using the olcnectl package on an operator node. For information on setting up an operator node, see Getting Started.

You interact with olcnectl by entering commands with a series of options. The Platform CLI syntax is:

olcnectl command {{-h|--help}|command_options}

The full syntax and options for each command is provided in Chapter 2, Platform CLI Commands.

When you use the olcnectl command, you are prompted for any missing options.

1.1 Getting Syntax Help

You can get help on the syntax for olcnectl commands using the --help option. For example, to show the command options available for the olcnectl command, enter:

olcnectl --help
A CLI that talks to an Oracle Linux Cloud Native Environment Platform API Server endpoint, facilitating deployment and management of Kubernetes clusters and their resources Usage: olcnectl [command] Available Commands: environment Environment operations help Help about any command module Modules that can be modified in an environment Flags: -a, --api-server string Platform API Server to talk to. If this is not specified ... -h, --help help for olcnectl --olcne-ca-path string Optional path to a predefined CA or the a destination if ... --olcne-node-cert-path string Optional path to a predefined Key or the a destination ... --olcne-node-key-path string Optional path to a predefined Cert or the a destination ... --olcne-tls-cipher-suites string TLS Cipher Suites, Possible value(s) (comma separated): ... --olcne-tls-max-version string TLS Maximum Version, Default value: VersionTLS12, ... --olcne-tls-min-version string TLS Minimum Version, Default value: VersionTLS12, ... --secret-manager-type string Manager that will handle the secrets. Options are: file, ... --update-config When defined the global arguments will be writen to a ... --vault-address string Address of Vault. Default: https://127.0.0.1:8200 or ... --vault-cert-sans string Sans that will passed to Vault to generate the Platform ... --vault-token string Token to authentic with Vault Use "olcnectl [command] --help" for more information about a command.

The Available Commands section lists any available commands for the olcnectl command. In this case, you can use the commands olcnectl environment, olcnectl help and olcnectl module.

The Flags section lists the available command options you can use. In this case, the options shown are also the global flags which are used by all subcommands. For more information on the global flags, see Section 1.3, “Using Global Flags”.

The olcnectl help command is the equivalent of using olcnectl --help. That is, it prints out the help for the olcnectl command.

You can drill further down into the help system by providing the --help option to the commands listed in the Available Commands section. For example, to show the available commands and options for the olcnectl module command, enter:

olcnectl module --help
Modules that are used to customize your environment Usage: olcnectl module [command] Available Commands: backup backup a module create Create a module get Get a module install Install a module instances List all module instances that are defined in an environment list Show all modules that can be installed property Commands that interact with module properties restore restore a module uninstall Uninstall a module update Update a module validate Validate that an module can be installed Flags: -h, --help help for module Global Flags: -a, --api-server string Platform API Server to talk to. If this is not specified ... -h, --help help for olcnectl --olcne-ca-path string Optional path to a predefined CA or the a destination if ... --olcne-node-cert-path string Optional path to a predefined Key or the a destination ... --olcne-node-key-path string Optional path to a predefined Cert or the a destination ... --olcne-tls-cipher-suites string TLS Cipher Suites, Possible value(s) (comma separated): ... --olcne-tls-max-version string TLS Maximum Version, Default value: VersionTLS12, ... --olcne-tls-min-version string TLS Minimum Version, Default value: VersionTLS12, ... --secret-manager-type string Manager that will handle the secrets. Options are: file, ... --update-config When defined the global arguments will be writen to a ... --vault-address string Address of Vault. Default: https://127.0.0.1:8200 or ... --vault-cert-sans string Sans that will passed to Vault to generate the Platform ... --vault-token string Token to authentic with Vault Use "olcnectl module [command] --help" for more information about a command.

Again, the Available Commands section lists any sub commands available for the command. In this case, you can use commands such as olcnectl module backup, olcnectl module create, olcnectl module get and so on.

The Global Flags section lists the global flags which can be used by all subcommands. This is the same list of options as shown earlier with the olcnectl --help command and listed under the Flags section.

Drilling further down into the help system you can see the olcnectl module property command has a further two options, get and list.

olcnectl module property --help
Commands that interact with module properties Usage: olcnectl module property [command] Available Commands: get Gets the value of one or more properties list Show all properties for a module Flags: -h, --help help for property ... Use "olcnectl module property [command] --help" for more information about a command.

To get a list of the command options you need to include the full command with the --help option. In this case, the olcnectl module property get command has four options as shown in the Flags section.

olcnectl module property get --help
Given a list of properties, fetch the value of each for a specific module Usage: olcnectl module property get [flags] Flags: -E, --environment-name string Name of the environment -h, --help help for get -N, --name string Name of the module -P, --property strings Names of properties to fetch ...

The help system for the olcnectl module create and the olcnectl module update commands behaves differently to the other uses of the --help option. As there are multiple modules within an environment, you must provide information about a module in order for the Platform CLI to display the appropriate help. To display the help for the olcnectl module create command, enter:

olcnectl module create --help
Create a module in a environment Usage: olcnectl module create [flags] Flags: -E, --environment-name string Name of the environment -h, --help help for create -M, --module strings Module to create -N, --name strings Name to assign the module ...

To see the options for creating each module you must use the --module option and provide the module type. The module types are listed in Section 2.4, “Module Create”. For example, to get help on creating a Kubernetes module you specify the module type as kubernetes:

olcnectl module create --help --module kubernetes
Create a module in a environment Usage: olcnectl module create [flags] Flags: -o, --apiserver-advertise-address string (DEPRECATED) Advertised address for internal ... -b, --apiserver-bind-port string Kubernetes API Server bind port (default "6443") -B, --apiserver-bind-port-alt string Port for the Kubernetes API Server to bind to if ... -e, --apiserver-cert-extra-sans string Kubernetes API Server extra sans -r, --container-registry string Container Registry that holds the kubernetes images -E, --environment-name string Name of the environment -h, --help help for create -x, --kube-proxy-mode string Routing mode for the Kubernetes proxy (default ... -v, --kube-version string Kubernetes version (default "1.17.4") ...

Similarly, to get help on the olcnectl module update command use:

olcnectl module update --help
Update a module Usage: olcnectl module update [flags] Flags: -E, --environment-name string Name of the environment -F, --force Update without prompting -g, --generate-scripts Generate a script for each node that takes all suggested actions -h, --help help for update -N, --name strings Modules to update ...

The output shows a --name option. This is the option you use to specify the module. This example shows the output for the olcnectl module update --help command for a Kubernetes module named mycluster:

olcnectl module update --help --name mycluster
Update a module Usage: olcnectl module update [flags] Flags: -E, --environment-name string Name of the environment -F, --force Update without prompting -g, --generate-scripts Generate a script for each node that takes all suggested actions -h, --help help for update -v, --kube-version string Kubernetes version (default "1.18.10") -m, --master-nodes string A comma separated list of master nodes -N, --name strings Modules to update -w, --worker-nodes string A comma separated list of worker nodes ...

The output shows the options you can use to scale or update/upgrade the Kubernetes module.

1.2 Setting the Platform API Server

The Platform CLI connects to an Oracle Linux Cloud Native Environment Platform API Server. You can use an operator node with the Platform CLI installed to connect to multiple Platform API Server instances. You specify the Platform API Server using the olcnectl --api-server api_server_address:8091 option. This enables you to use a single operator node to manage multiple environments. For example, to connect to a Platform API Server on apiserver.example.com, you would use:

olcnectl module property list \
--api-server apiserver.example.com:8091 \
--environment-name myenvironment \
--name mycluster

When you create an environment with the olcnectl environment create command you can optionally include the --update-config option. This option writes information about the environment to a local configuration file at $HOME/.olcne/olcne.conf, and this configuration is used for future calls to the Platform API Server. If you use this option, you do not need to specify the Platform API Server in future olcnectl commands.

For example, if you create an environment using the --update-config option:

olcnectl environment create \
--api-server 127.0.0.1:8091 \
--environment-name myenvironment \
--secret-manager-type vault \
--vault-token s.3QKNuRoTqLbjXaGBOmO6Psjh \
--vault-address https://192.0.2.20:8200 \
--update-config 

When you write all future olcnectl commands you can omit the --api-server option. For example:

olcnectl module property list \
--environment-name myenvironment \
--name mycluster

You can also set an environment variable to set the Platform API Server. You can do this using the $OLCNE_API_SERVER_BIN environment variable on the operator node. For example, to set the Platform API Server to the localhost, use:

export OLCNE_API_SERVER_BIN=127.0.0.1:8091

1.3 Using Global Flags

There are a number of global flags, or command options, that can be used with all olcnectl commands.

These options are most often used when creating an environment using the olcnectl environment create command, however they can also be used with all other olcnectl commands. The global options are:

[{-a|--api-server} api_server_address:8091]
[--secret-manager-type {file|vault}]
[--update-config]
[--olcne-ca-path ca_path]
[--olcne-node-cert-path node_cert_path]
[--olcne-node-node-key-path node_key_path]
[--olcne-tls-cipher-suites ciphers]
[--olcne-tls-max-version version]
[--olcne-tls-min-version version]
[--vault-address vault_address]
[--vault-cert-sans vault_cert_sans]
[--vault-token vault_token]

Where:

{-a|--api-server} api_server_address:8091

The Platform API Server for the environment. This is the host running the olcne-api-server service in an environment. The value of api_server_address is the IP address or hostname of the Platform API Server. The port number is the port on which the olcne-api-server service is available. The default port is 8091.

If a Platform API Server is not specified, a local instance is used. If no local instance is set up, it is configured in the $HOME/.olcne/olcne.conf file.

For more information on setting the Platform API Server see Section 1.2, “Setting the Platform API Server”.

This option maps to the $OLCNE_API_SERVER_BIN environment variable. If this environment variable is set it takes precedence over and overrides the Platform CLI setting.

--secret-manager-type {file|vault}

The secrets manager type. The options are file or vault. Use file for certificates saved on the nodes and use vault for certificates managed by Vault.

--update-config

Writes the global arguments for an environment to a local configuration file which is used for future calls to the Platform API Server. If this option has not been used previously, global arguments must be specified for every Platform API Server call.

The global arguments configuration information is saved to $HOME/.olcne/olcne.conf on the local host.

If you use Vault to generate certificates for nodes, the certificate is saved to $HOME/.olcne/certificates/environment_name/ on the local host.

--olcne-ca-path ca_path

The path to a predefined Certificate Authority certificate, or the destination of the certificate if using a secrets manager to download the certificate. The default is /etc/olcne/certificates/ca.cert, or gathered from the local configuration if the --update-config option is used.

This option maps to the $OLCNE_SM_CA_PATH environment variable. If this environment variable is set it takes precedence over and overrides the Platform CLI setting.

--olcne-node-cert-path node_cert_path

The path to a predefined key, or the destination of the key if using a secrets manager to download the key. The default is /etc/olcne/certificates/node.key, or gathered from the local configuration if the --update-config option is used.

This option maps to the $OLCNE_SM_CERT_PATH environment variable. If this environment variable is set it takes precedence over and overrides the Platform CLI setting.

--olcne-node-key-path node_key_path

The path to a predefined certificate, or the a destination if using a secrets manager to download the certificate. The default is /etc/olcne/certificates/node.cert, or gathered from the local configuration if the --update-config option is used.

This option maps to the $OLCNE_SM_KEY_PATH environment variable. If this environment variable is set it takes precedence over and overrides the Platform CLI setting.

--olcne-tls-cipher-suites ciphers

The TLS cipher suites to use for Oracle Linux Cloud Native Environment services (the Platform Agent and Platform API Server). Enter one or more in a comma separated list. The options are:

  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA

  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256

  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

  • TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305

  • TLS_ECDHE_ECDSA_WITH_RC4_128_SHA

  • TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA

  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

  • TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305

  • TLS_ECDHE_RSA_WITH_RC4_128_SHA

  • TLS_RSA_WITH_3DES_EDE_CBC_SHA

  • TLS_RSA_WITH_AES_128_CBC_SHA

  • TLS_RSA_WITH_AES_128_CBC_SHA256

  • TLS_RSA_WITH_AES_128_GCM_SHA256

  • TLS_RSA_WITH_AES_256_CBC_SHA

  • TLS_RSA_WITH_AES_256_GCM_SHA384

  • TLS_RSA_WITH_RC4_128_SHA

For example:

--olcne-tls-cipher-suites TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

This option maps to the $OLCNE_TLS_CIPHER_SUITES environment variable. If this environment variable is set it takes precedence over and overrides the Platform CLI setting.

--olcne-tls-max-version version

The TLS maximum version for Oracle Linux Cloud Native Environment components. The default is VersionTLS12. Options are:

  • VersionTLS10

  • VersionTLS11

  • VersionTLS12

  • VersionTLS13

This option maps to the $OLCNE_TLS_MAX_VERSION environment variable. If this environment variable is set it takes precedence over and overrides the Platform CLI setting.

--olcne-tls-min-version version

The TLS minimum version for Oracle Linux Cloud Native Environment components. The default is VersionTLS12. Options are:

  • VersionTLS10

  • VersionTLS11

  • VersionTLS12

  • VersionTLS13

This option maps to the $OLCNE_TLS_MIN_VERSION environment variable. If this environment variable is set it takes precedence over and overrides the Platform CLI setting.

--vault-address vault_address

The IP address of the Vault instance. The default is https://127.0.0.1:8200, or gathered from the local configuration if the --update-config option is used.

--vault-cert-sans vault_cert_sans

Subject Alternative Names (SANs) to pass to Vault to generate the Oracle Linux Cloud Native Environment certificate. The default is 127.0.0.1, or gathered from the local configuration if the --update-config option is used.

--vault-token vault_token

The Vault authentication token.