k8s porx Logo

Interactive Tutorial

Following are some interactive tutorials that give an overview about Portworx on Kubernetes.

Prerequisites

Key-value store

Portworx uses a key-value store for it’s clustering metadata. Please have a clustered key-value database (etcd or consul) installed and ready. For etcd installation instructions please refer to this doc.

Storage

At least one of the Portworx nodes should have extra storage available, in a form of unformatted partition or a disk-drive.

Storage devices explicitly given to Portworx will be automatically formatted by PX.

Shared mounts

If you are running Docker v1.12, you must configure Docker to allow shared mounts propagation (see instructions), as otherwise Portworx will fail to start.

Firewall

Ensure ports 9001-9015 are open between the nodes that will run Portworx.

NTP

Ensure all nodes running PX are time-synchronized, and NTP service is configured and running..

Install

Portworx gets deployed as a Kubernetes DaemonSet. Following sections describe how to generate the spec files and apply them.

Generating the spec

To generate the spec file for the 1.3 release, head on to 1.3 install page.

To generate the spec file for the 1.2 release, head on to 1.2 install page.

Alternately, you can use curl to generate the spec as described in Generating Portworx Kubernetes spec using curl.

Secure ETCD and Certificates

If using secure etcd provide “https” in the URL and make sure all the certificates are in the /etc/pwx/ directory on each host which is bind mounted inside PX container.

Using Secrets to Provision Certificates

It is recommended to use Kubernetes Secrets to provide ETCD certificates to Portworx. This way, the certificates will be automatically mounted when new nodes join the cluster.

Copy all your etcd certificates and key in a folder etcd-secrets/ to create a Kubernetes secret from it.

# ls etcd-secrets
etcd-ca etcd-cert   etcd-key

Use kubectl to create the secret named px-etcd-certs from the above files:

# kubectl -n kube-system create secret generic px-etcd-certs --from-file=etcd-secrets/

Now edit the Portworx spec file to reference the certificates. Given the names of the files are etcd-ca, etcd-cert and etcd-key, modify the volumeMounts and volumes sections as follows:

  volumeMounts:
  - mountPath: /etc/pwx/etcdcerts
    name: etcdcerts
  volumes:
  - name: etcdcerts
    secret:
      secretName: px-etcd-certs
      items:
      - key: etcd-ca
        path: pwx-etcd-ca.crt
      - key: etcd-cert
        path: pwx-etcd-cert.crt
      - key: etcd-key
        path: pwx-etcd-key.key

Now that the certificates are mounted at /etc/pwx/etcdcerts, change the portworx container args to use the correct certificate paths:

  containers:
  - name: portworx
    args:
      ["-c", "test-cluster", "-a", "-f",
      "-ca", "/etc/pwx/etcdcerts/pwx-etcd-ca.crt",
      "-cert", "/etc/pwx/etcdcerts/pwx-etcd-cert.crt",
      "-key", "/etc/pwx/etcdcerts/pwx-etcd-key.key",
      "-x", "kubernetes"]

Installing behind the HTTP proxy

During the installation Portworx may require access to the Internet, to fetch kernel headers if they are not available locally on the host system. If your cluster runs behind the HTTP proxy, you will need to expose PX_HTTP_PROXY and/or PX_HTTPS_PROXY environment variables to point to your HTTP proxy when starting the DaemonSet.

Use e=PX_HTTP_PROXY=<http-proxy>,PX_HTTPS_PROXY=<https-proxy> query param when generating the DaemonSet spec.

Applying the spec

Once you have generated the spec file, deploy Portworx.

$ kubectl apply -f px-spec.yaml

Monitor the portworx pods

kubectl get pods -o wide -n kube-system -l name=portworx

Monitor Portworx cluster status

PX_POD=$(kubectl get pods -l name=portworx -n kube-system -o jsonpath='{.items[0].metadata.name}')
kubectl exec $PX_POD -n kube-system -- /opt/pwx/bin/pxctl status

If you are still experiencing issues, please refer to Troubleshooting PX on Kubernetes and General FAQs.

Deploy a sample application

Now that you have Portworx installed, checkout various examples of applications using Portworx on Kubernetes.