Skip to content

Latest commit

 

History

History
208 lines (132 loc) · 8.31 KB

DeploymentDocumentation.md

File metadata and controls

208 lines (132 loc) · 8.31 KB
Raw

Deployment Documentation

About

This is documentation for the steps necessary to deploy upsin server in an openshift cluster. After following all steps, a user can expect to have a running Upspin server on OpenShift.

This documentation is an extension to the original Upspin documentation, which is the basis for this deployment. The goal of this document is to guide a user through deploying an Upspin server on a OpenShift cluster with default pod configurations.

Prerequisites for setup

  • Latest OC command line client. documenation

  • Latest version of Upspin command line tool on local machine: documentation

  • Verified email for your Upspin account : documentation

    • ex: johnsmith@gmail.com

  • Custom domain and hostname:

    • example domain: myUpspin.com
    • example hostname: john.myUpspin.com

  • Set up ACME controller in OpenShift cluster

    • Run the following commands after you logged into your OpenShift namespace:
    oc apply -fhttps://raw.githubusercontent.com/tnozicka/openshift-acme/master/deploy/single-namespace/{role,serviceaccount,issuer-letsencrypt-live,deployment}.yaml
oc create rolebinding openshift-acme --role=openshift-acme --serviceaccount="$( oc project -q ):openshift-acme" --dry-run -o yaml | oc apply -f -

    On success, you should see a running application in your OpenShift namespace called openshift-acme. You could check more details at ACME Controller.

1. Create app with template.yaml (More details)

I. Modify template file

  • Download the template.yaml
  • Edit the parameters at the bottom of the template file, only these parameters need to be changed:
    • DEPLOYMENT_NAME
    • HOST_NAME
    • OPENSHIFT_HOST_NAME
    • PVC_NAME
  • Edit template name :
    • metadata > name:

II. Deploy new app with template:

Build template: This step will create the template resource from the given configuration file and add it to the openshift namespace.

oc create -f template.yaml

Create app: This step creates the application using the template created in previous step.

oc new-app <template_name>
  • Upon successful running of the above command, you should see creation messages for all the OpenShift primitives present in the template.

2. Add CNAME record to your hostname

  • This will tell your hostname to point at your application on OpenShift.
  • Need to add a CNAME record for your given hostname
  • Content should be the OpenShift auto-generated hostname of your app

Cloudflare API example :

curl -X POST "<CloudFlare API link>" \
     -H "Authorization: Bearer <HIDDEN KEY>" \
     -H "Content-Type: application/json" \
		 --data '{"type":"CNAME","name":"<your hostname>","content":"<hostname of your app generated by Openshift>","ttl":120,"proxied":false}'

Note: This step will vary according to the service which is providing with the hostname. For our setup we used Cloudflare.

3. Setup domain

I. Setup your custom domain with Upspin

upspin setupdomain -domain=<your domain>

II. Create text DNS record for your domain.

  • Follow instructions from the command line setupdomain output.
  • Consult your DNS management tool documentation for specific instructions as they may vary.

Can verify it was placed succesfully with the following command:

host -t TXT <your domain>

4. Configure Server

Note: Might need to wait a few minutes for everything above to complete - we recommend waiting at least 2 minutes.

I. Setup server via Upspin

upspin setupserver -domain=<your domain> -host=<your custom hostname>

This command will setup the server, but further details can be found at the upspin documentation.

5. Verify Successful Configuration

You should now be able to read and write to your server. Try the following command to test it out!

local$ echo Hello, Upspin | upspin put johnsmith@gmail.com/hello

Note: from now on in the documentation, the command line prefix "local$" indicates that this command should be running locally and not within the Upspin terminal on OpenShift.

Now you can try to read what you wrote back.

local$ upspin get johnsmith@gmail.com/hello
Hello, Upspin

6. Clean up

In event of a deployment fail or updates to the template for a new deployment, you can use the following commands to clean up the build and to avoid running into conflicts with the new build. The commands below correspond to these four features, respectively:

  • Deleting all resources created for a deployment
  • Deleting a specific template
  • Deleting an image stream tag
  • Deleting a persistent volume claim
local$ oc delete all --selector app=<deployment_name>

local$ oc delete template/<template_name>

local$ oc delete is/<image_stream_tag_name>

local$ oc delete pvc/<persistent_volume_claim_name>

You may also find these commands helpful, which can be used in the following ways:

  • To see a list of all the resources that have been created in the cluster
  • To get more details about a primitive, such as pod, service, deployment config, route, image stream, persistent volume claim, etc...
local$ oc get all -o name

local$ oc describe route/<name>

7. Appendix

1. ACME Controller

The two commands deploy the ACME controller to manage TLS certificate of your hostname automatically. LetsEncrypt has rate limiting on number of times a domain has been issued with a certificate. ACME controller's documentation has information about running the client in Dev mode which does not have any rate limiting.

After CNAME step, you should see an annotation is added to the route in OpenShift, as well as auto-generated certificate and private key.

It may take time for ACME controller to generate TLS certificate for a given hostname. In case of downtime of the ACME controller, you could use Certbot client of Let's Encrypt to get a TLS certificate. The process can be found here.

2. OpenShift Template

Openshift template describes configurations of necessary cluster's primitives including routes, services, build configurations, and persistent volumes. With these parameters, a user may customize the build.

  • Deployment - this template provides specifications of Deployment - native API object type in OpenShift Container Platform - which describes the desired state of a particular component of an application as a Pod template, and orchestrates Pod lifecycles.

    Here, you could also specify Persistent Volume (PV) - a piece of storage in the cluster - and Persistent Volume Claim (PVC) - a request for storage resources. They connect specific filesystem paths of the service back to the OpenShift cluster, so that data is persisted in event of a pod scaled, deleted or restarted, to allow for continuous integration.

  • Image stream tag- this template specifies the image stream and its associated tags, which provides an abstraction for referencing Docker images from within OpenShift Container Platform.

  • Service - with service object defined, it serves as an internal load balancer, and identifies a set of replicated pods. Backing pods can be added to or removed from a service arbitrarily while the service remains consistently available. It also provides the mapping between the service port and the actual pod port.

  • Route - a container route would route the traffic of a certain host name to the designated service at the target port, so that external clients can reach the expected service by hostname.

3. Persistent Volumes

Our template uses a persistent volume, so the file is kept even if a pod is scaled down, up, or deleted.

// delete pod
local$ oc delete pod/<pod name>
pod "<pod name>" deleted

// After a new pod is initialized automatically by OpenShift
local$ upspin get you@gmail.com/hello          
Hello, Upspin