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 for 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.12.2

      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 1.17.9.

    • [-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.

    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 3.1.1.

    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 2.13.1.

    • [--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 1.4.10.

    • [--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 1.17.9. 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.

    • [--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.

  • 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.