This tutorial guides you through the process of deploying a simple service onto k8s using a hspec (HyScale Service Spec) and the hyscale command line tool.

The hyscale tool reads the supplied hspec and performs the necessary actions needed for deployment to k8s such as preparing a dockerfile, building the docker image and generating the various k8s manifests needed to satisfy the items declared in the hspec.

1. Getting started with your first hspec

1.1 Declaring service name

To begin with the hspec file should declare a name for your service:

name: my-service-name

This service name acts as the DNS name for service discovery so that other services can communicate.

IMPORTANT: Any relative paths referred in the below sections should be relative to the hspec file and cannot refer paths parent to the folder containing the hspec file.

1.2 Pointing to service images

1.2.1 Pull from image registry

name: sampleproject/myservice
tag: 1.0

The above snippet specifies the final image to be deployed within k8s. Make sure your cluster has access to the registry mentioned. If you are building images on your own, the above should suffice.

For hyscale to generate this image for you, there are 2 possible starting points for your service:

  • You have either the source code (eg. php files) or binaries (eg. war file) for your service.

  • You have a docker file for your service.

For each of these 2 cases, use the snippets given below and modify as needed:

1.2.2 Generate and add images from source/binaries

To start from source, or binaries for compiled languages, place this buildSpec snippet under the image directive:

stackImage: tomcat:8.5.0-jre8
- name: myservice
source: target/myservice.war
destination: /usr/local/tomcat/webapps/

stackImage is the stack (base image) that your code depends on. Simply providing a name:version will pull the image from docker hub by default. If you need to pull from a different repository, specify the full path in the format: registry-url/name:version

Under artifacts

  • name is simply an identifier for your source/binary artifacts
  • source specifies the relative path to the artifacts including the filename. This can be a zip file but not a folder.
  • destination specifies the absolute path inside the container where the artifacts should be placed.

hyscale will generate the dockerfile & docker image as per the buildSpec above. For more options on buildSpec , the full spec reference here

1.2.3 Use existing Docker images

Include this line if you already have a dockerfile for your service

dockerfile: {}

Hyscale will look for a “Dockerfile” in the same directory as the hspec file. If you require to specify a different path to the Dockerfile, or a different name of the Dockerfile or any build arguments, see the full spec reference here.

1.3 Other top-level directives for deployment

  • 1.3.1 Ports - - To expose ports on which your service listens eg: tomcat on 8080, redis on 6379 etc.

    - port: 8080
    healthCheck: {}

    For more options, see the full spec reference here.

    NOTE: ServicePorts & ContainerPorts are generated from this. If you specify a healthCheck, generates container readiness & liveness probes.

  • 1.3.2 Volumes (for persistence) - - To specify folders that store data & need persistence.

    - name: tomcat-logs
    path: /usr/local/tomcat/logs
    size: 1Gi

    For more options, see the full spec reference here.

    NOTE: This snippet results in Statefulset for your service and Volume claim templates that bring up PVCs attached to default storage class.

  • 1.3.3 Environment properties - - If your service needs certain environment properties.

    JAVA_HOME: /usr/local/java
    TOMCAT_HOME: /usr/local/tomcat
    propsVolumePath: /usr/local/data/config/tomcat.props

    NOTE: props are generated as a configMap and injected as environment variables in the container. If propsVolumePath is specified, the map is also configured to be mounted as a volume attached to the pod.

  • 1.3.4 Secrets - - If your service needs certain secrets, specify one of the following:


    The above snippet specifies the list of keys that your service needs access to. The values are automatically referred at run-time using the secret name “-” in your namespace, which should have been pre-created by your k8s admin. For more details on this, see here.



    In this case, typically useful for dev/test, the snippet specifies the secret key-value pairs needed by the service.

    NOTE: hyscale creates a secret with the specified key-value pairs within your namespace and if secretsVolumePath is specified, also mounts the secrets as a volume at the path location inside the container.

  • 1.3.5 Exposing service - - To expose your service outside of the k8s cluster.

    external: true 

    NOTE: Generates service type as LoadBalancer. If this is not specified a ClusterIP is generated.

1.4 Other hspec directives and examples

If you need to specify certain startup commands, or memory/cpu limits, number of replicas, etc. refer the full service spec doc here.

Make sure to name your hspec file as per the service name specified inside your file. So if your service name is myservice your hspec file should be myservice.hspec.yaml For some example hspec files, see here.

2. Deploying with your hspec

Once you’ve written a hspec file as per the above, simply to deploy to k8s using

hyscale deploy service -f myservice.hspec.yaml -n sample-dev -a sampleapp

Where, -f specifies path to your hspec, -n is the k8s namespace given to you by your k8s admin (a namespace is created if it doesn’t exist) and -a specifies an identifier for your app name as decided by you.

After its done, you should be getting a service IP on the screen such as:

To verify that its properly deployed or to check for issues, you can verify the status:

hyscale get service status -s myservice -n sample-dev -a sampleapp

To look into the logs or tail the logs for debugging

hyscale get service logs -s myservice -n sample-dev -a sampleapp -tail

See here for full command reference.