The software described in this documentation is either no longer supported or is in extended support.
Oracle recommends that you upgrade to a current supported release.

Chapter 5 Using the Platform CLI

This chapter discusses using the Platform CLI, the olcnectl command.

5.1 Platform CLI Syntax

The Platform CLI, olcnectl, is used to configure, deploy and manage the components of the Oracle Linux Cloud Native Environment. You interact with olcnectl by entering commands with a series of options.

The Platform CLI syntax is:

olcnectl [options] command [command_options]

Where options is one or more of:

```
{-a|--api-server} api_server_address:8091 
```
The value of api_server_address is the IP address or hostname of the Platform API Server.
If an Platform API Server is not specified, a local instance of an Platform API Server is created and used.
```
--olcne-ca-path ca_path
```
(Optional) 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.
```
--olcne-node-cert-path node_cert_path
```
(Optional) 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.
```
--olcne-node-node-key-path node_key_path
```
(Optional) 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.
```
--secret-manager-type {file|vault}
```
The secrets manager type. The options are file or vault.
```
--update-config 
```
When defined, the global arguments are written to a local configuration file and 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.
```
--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.

And where command is one of:

```
environment {create|delete} {-E|--environment-name} environment_name 
```
Creates an empty environment, or deletes an existing environment.

module list {-E|--environment-name} environment_name

Lists the available modules for an environment.

```
module create {-E|--environment-name} environment_name {-M|--module} module_name {-N|--name} name [module_args ...]
```
Adds and configures a module in an environment.
The value of module_args is one or more arguments to configure a module in an environment.
module_args for the kubernetes module:
- ```
[-r|--container-registry] container_registry
```
  The container registry that contains the Kubernetes images.
  If you do not provide this value, you are prompted for it by the Platform CLI.
- ```
[-m|--master-nodes] nodes ...
```
  A comma separated list of the hostnames or IP addresses of the Kubernetes master nodes, including the port number for the Platform Agent. The default port is 8090. For example, master1.example.com:8090,master2.example.com:8090.
  If you do not provide this value, you are prompted for it by the Platform CLI.
- ```
[-w|--worker-nodes] nodes ...
```
  A comma separated list of the hostnames or IP addresses of the Kubernetes worker nodes, including the port number for the Platform Agent. The default port is 8090. For example, worker1.example.com:8090,worker2.example.com:8090.
  If you do not provide this value, you are prompted for it by the Platform CLI.
- ```
[-l|--load-balancer] load_balancer
```
  The Kubernetes API server load balancer hostname or IP address, and port. The default port is 6443. For example, 192.0.2.100:6443.
- ```
[--virtual-ip] virtual_ip
```
  The virtual IP address for the load balancer. This is optional.
  You should use this option if you do not specify your own load balancer using the --load-balancer option. When you specify a virtual IP address, it is used as the primary IP address for master nodes.
- ```
[--apiserver-bind-port-alt] port
```
  The port on which the Kubernetes API server listens when you use a virtual IP address for the load balancer. The default is 6444. This is optional.
  When you use a virtual IP address, the Kubernetes API server port is changed from the default of 6443 to 6444. The load balancer listens on port 6443 and receives the requests and passes them to the Kubernetes API server. If you want to change the Kubernetes API server port in this situation from 6444, you can use this option to do so.
- ```
[--nginx-image] container_location
```
  The location of an NGINX container image to use in a multi-master deployment. This is optional.
  You can use this option if you do not provide your own load balancer using the --load-balancer option. This option may be useful if you are using a mirrored container registry. For example:
```
--nginx-image host.example.com:5000/olcne/nginx:1.17.7
```
  By default, podman is used to pull the NGINX image that is configured in /usr/libexec/pull_olcne_nginx. If you set the --nginx-image option to use another NGINX container image, the location of the image is written to /etc/olcne-nginx/image, and overrides the default image.
- ```
[-k|--kube-version] version
```
  The Kubernetes version to deploy. The default is the latest version. For information on the latest version number, see Release Notes.
- ```
[-t|--kubeadm-token] token
```
  The token to use for establishing bidirectional trust between Kubernetes nodes and control-plane nodes. The format is [a-z0-9]{6}\.[a-z0-9]{16}, for example, abcdef.0123456789abcdef.
- ```
[-o|--apiserver-advertise-address] IP_address
```
  The IP address on which to advertise the Kubernetes API server to members of the Kubernetes cluster. This address must be reachable by the cluster nodes. If no value is provided, the master node's default interface is used.
  This option is not used in a multi-master, high availability deployment.
- ```
[-b|--apiserver-bind-port] port
```
  The Kubernetes API server bind port. The default is 6443.
- ```
[-s|--service-cidr] service_CIDR
```
  The Kubernetes service CIDR. The default is 10.96.0.0/12. This is the range from which each Kubernetes service is assigned an IP address.
- ```
[-p|--pod-cidr] pod_CIDR
```
  The Kubernetes pod CIDR. The default is 10.244.0.0/16. This is the range from which each Kubernetes pod network interface is assigned an IP address.
- ```
[-x|--kube-proxy-mode] {userspace|iptables|ipvs}
```
  The routing mode for the Kubernetes proxy. The default is iptables. The available proxy modes are:
  - userspace: This is an older proxy mode.
  - iptables: This is the fastest proxy mode. This is the default mode.
  - ipvs: This is an experimental mode.
  If no value is provided, the default of iptables is used. If the system's kernel or iptables version is insufficient, the userspace proxy is used.
- ```
[-e|--apiserver-cert-extra-sans] api_server_sans
```
  The Subject Alternative Names (SANs) to use for the Kubernetes API server serving certificate. This value can contain both IP addresses and DNS names.
- ```
[-n|--pod-network] network_fabric
```
  The network fabric for the Kubernetes cluster. The default is flannel.
- ```
--restrict-service-externalip {true|false}
```
  Sets whether to restrict access to external IP addresses for Kubernetes services. The default is true, which restricts access to external IP addresses.
  This option deploys a Kubernetes service named externalip-validation-webhook-service to validate externalIPs set in Kubernetes service configuration files. Access to any external IP addresses is set in a Kubernetes service configuration file using the externalIPs option in the spec section.
- ```
--restrict-service-externalip-ca-cert path
```
  The path to a CA certificate file for the externalip-validation-webhook-service application that is deployed when the --restrict-service-externalip option is set to true. For example, /etc/olcne/configs/certificates/restrict_external_ip/production/ca.cert.
- ```
--restrict-service-externalip-tls-cert path
```
  The path to a CA certificate file for the externalip-validation-webhook-service application that is deployed when the --restrict-service-externalip option is set to true. For example, /etc/olcne/configs/certificates/restrict_external_ip/production/node.cert.
- ```
--restrict-service-externalip-tls-key path
```
  The path to the private key for the externalip-validation-webhook-service application that is deployed when the --restrict-service-externalip option is set to true. For example, /etc/olcne/configs/certificates/restrict_external_ip/production/node.key.
- ```
--restrict-service-externalip-cidrs allowed_cidrs
```
  Enter one or more comma separated CIDR blocks if you want to allow only IP addresses from the specified CIDR blocks. For example, 192.0.2.0/24,198.51.100.0/24.
module_args for the helm module:
- ```
[--helm-kubernetes-module] kubernetes_module
```
  The name of the kubernetes module instance that Helm should be installed into. Each instance of Kubernetes can have one instance of Helm associated with it.
- ```
[--helm-version] version
```
  The version of Helm to deploy. The default is the latest version. For information on the latest version number, see Release Notes.
module_args for the prometheus module:
- ```
[--prometheus-helm-module] helm_module
```
  The name of the helm module instance that Prometheus should be associated with.
- ```
[--prometheus-image] container_registry
```
  The container image registry and tag to use when deploying Prometheus. The default is container-registry.oracle.com/olcne/prometheus.
- ```
[--prometheus-version] version
```
  The version of Prometheus to deploy. The default is the latest version. For information on the latest version number, see Release Notes.
- ```
[--prometheus-persistent-storage] {true|false}
```
  If this value is false, Prometheus writes its data into an emptydir on the host where the pod is running. If the pod migrates, metric data is lost.
  If this value is true, Prometheus requisitions a Kubernetes PersistentVolumeClaim so that its data persists, despite destruction or migration of the pod.
  The default is false.
  Important
  Oracle Linux Cloud Native Environment does not yet have any modules that provide support for Kubernetes PersistentVolumeClaims, so persistent storage must be manually set up.
module_args for the istio module:
- ```
[--istio-helm-module] helm_module
```
  The name of the helm module instance that Istio should be associated with. This instance of Helm is used to install the Istio module.
- ```
[--istio-container-registry] container_registry
```
  The container image registry to use when deploying Istio. The default is container-registry.oracle.com/olcne.
- ```
[--istio-version] version
```
  The version of Istio to deploy. The default is the latest version. For information on the latest version number, see Release Notes.
- ```
[--istio-mutual-tls] {true|false}
```
  Sets whether to enable Mutual Transport Layer Security (mTLS) for communication between the control plane pods for Istio, and for any pods deployed into the Istio service mesh.
  The default is true.
  Important
  It is strongly recommended that this value is not set to false, especially in production environments.
```
module {validate|install} {-E|--environment-name} environment_name {-N|--name} name [--generate-scripts]
```
Validates or installs a module for an environment. When you validate a module, the nodes are checked to make sure they are set up correctly to run the module. If the nodes are not set up correctly, the commands required to fix each node is shown in the output.
- ```
[--generate-scripts]
```
  Generates a script which contains the commands required to fix any set up errors for the nodes in a module. A script is created for each node in the module, saved to the local directory, and named hostname:8090.sh.
```
module update {-E|--environment-name} environment_name {-N|--name} name [module_args ...]
```
Updates a module for an environment. The module configuration is automatically retrieved from the Platform API Server. This command can be used to update the version of Kubernetes and to scale a cluster.
Where module_args is optionally one or more of:
- ```
[-k|--kube-version]
```
  Sets the Kubernetes version to upgrade to on the nodes. The default is the latest version. For information on the latest version number, see Release Notes.
  If this option is not provided when updating a Kubernetes module, any Kubernetes errata updates are installed.
- ```
[-m|--master-nodes] nodes ...
```
  A comma-separated list of the hostnames or IP addresses of the Kubernetes master nodes that should remain in or be added to the Kubernetes cluster, including the port number for the Platform Agent. Any master nodes not included in this list are removed from the cluster.
  The default port number for the Platform Agent is 8090. For example, master1.example.com:8090,master2.example.com:8090.
- ```
[-w|--worker-nodes] nodes ...
```
  A comma-separated list of the hostnames or IP addresses of the Kubernetes worker nodes that should remain in or be added to the Kubernetes cluster, including the port number for the Platform Agent. Any worker nodes not included in this list are removed from the cluster.
  The default port number for the Platform Agent is 8090. For example, worker1.example.com:8090,worker2.example.com:8090.
- ```
[--nginx-image] container_location
```
  The location of the NGINX container image to update. This is optional.
  This option pulls the NGINX container image from the container registry location you specify to update NGINX on the master nodes. For example:
```
--nginx-image container-registry.oracle.com/olcne/nginx:1.17.7
```
- ```
[--generate-scripts]
```
  Generates a script which contains the commands required to fix any set up errors for the nodes in a module. A script is created for each node in the module, saved to the local directory, and named hostname:8090.sh.
- ```
[--force]
```
  Skips the confirmation prompt when scaling or updating a Kubernetes cluster.
- ```
--restrict-service-externalip {true|false}
```
  Sets whether to restrict access to external IP addresses for Kubernetes services. The default is true, which restricts access to external IP addresses.
  This option deploys a Kubernetes service named externalip-validation-webhook-service to validate externalIPs set in Kubernetes service configuration files. Access to any external IP addresses is set in a Kubernetes service configuration file using the externalIPs option in the spec section.
- ```
--restrict-service-externalip-ca-cert path
```
  The path to a CA certificate file for the externalip-validation-webhook-service application that is deployed when the --restrict-service-externalip option is set to true. For example, /etc/olcne/configs/certificates/restrict_external_ip/production/ca.cert.
- ```
--restrict-service-externalip-tls-cert path
```
  The path to a CA certificate file for the externalip-validation-webhook-service application that is deployed when the --restrict-service-externalip option is set to true. For example, /etc/olcne/configs/certificates/restrict_external_ip/production/node.cert.
- ```
--restrict-service-externalip-tls-key path
```
  The path to the private key for the externalip-validation-webhook-service application that is deployed when the --restrict-service-externalip option is set to true. For example, /etc/olcne/configs/certificates/restrict_external_ip/production/node.key.
- ```
--restrict-service-externalip-cidrs allowed_cidrs
```
  Enter one or more comma separated CIDR blocks if you want to allow only IP addresses from the specified CIDR blocks. For example, 192.0.2.0/24,198.51.100.0/24.

module uninstall {-E|--environment-name} environment_name {-N|--name} name

Uninstalls a module for an environment.

module {backup|restore} {-E|--environment-name} environment_name {-N|--name} name

Backs up or restores a module for an environment.

module property list {-E|--environment-name} environment_name {-N|--name} name

Lists the available properties for a module in an environment.

module property get {-E|--environment-name} environment_name {-N|--name} name --property property_name

Lists the value of the property for a module in an environment.

And where command_options is one or more of:

```
{-E|--environment-name} environment_name
```
The value of environment_name is the name to use to identify an Oracle Linux Cloud Native Environment environment. An environment is a namespace that encapsulates software installed and managed by Oracle Linux Cloud Native Environment.
```
{-M|--module} module_name 
```
The value of module_name is the name of an Oracle Linux Cloud Native Environment module.
For information on available modules, see Section 3.3, “Introduction to Modules”.
```
{-N|--name} name 
```
The value of name is the name to use to identify a module in an environment.
```
--property property_name 
```
The value of property-name is the name used to identify a module property in an environment. You can get a list of the available properties for a module using the olcnectl module property list command.