Deployment Documentation

This page will describe the list of sections that are needed for the Deployment Documentation URL

Deployment Documentation Sections:

Mandatory Instruction Sections:

  1. 1.
    Prerequisites
  2. 2.
    Install / Deployment instructions
  3. 3.
    Uninstall/Reinstall instructions
  4. 4.
    Support/Help documentation
  5. 5.
    Sales Support Details

Optional Instruction Sections:

  1. 1.
    Workflow Details
  2. 2.
    Threat Model description
  3. 3.
    Troubleshooting Guide

Detailed description for each section with examples

Mandatory Instruction Sections

1. Prerequisites

This section describes the hardware and software resource dependencies required to install the application.
Example:
To deploy application X on Cloud Pak for Data, the following requirements must be met:
Hardware Requirements:
  • Min CPU:
  • Min Memory:
  • Min Storage:
  • Min Worker/Master Nodes:
  • Number of Pods/Replicas:
  • Hardware Security Exceptions if any (Link and configuration details):
In addition to documenting resource requirements in the deployment documentation, it’s recommended you specify those resource requirements as part of the deployment configuration. For example, deployment charts should explicitly specify their requirements using resource requests and limits for cpu and memory, preferably via values.yaml allowing customers to override those parameters during deployment.
Node role
Hardware
Number of servers
Available vCPU
Memory
Master + infra
x86-64
1 master and 1 infrastructure on the same node
8 vCPU
32 GB RAM
Worker/compute
x86-64
2 worker/compute nodes for NFS; 3 worker/compute nodes for Portworx
16 vCPU
64 GB RAM
Software Requirements:
  • Storage Class Software requirements: Portworx, NFS
  • OS/Network Virtualization requirements:
  • Security Software requirements:
  • Third party Software requirements:
  • Specific version dependencies:
Security Requirements:
Detailed information on security requirements is provided in the following two documents available in the Service Integration section:
1. The “Security Hardened for RHOS Cluster Deployment” section in Service Integration outlines general security requirements that need to be met when deploying a workload onto RHOS/CPD.
  • No cluster administrator privileges – typically deployment would be into its own namespace with privileges limited to that namespace. Any actions requiring cluster-admin privileges need to be explicitly stated.
  • No direct (i.e. ssh access to cluster nodes)
  • Outbound connectivity may be restricted
  • Container images need to run as non-root user
  • No host access or host mounts
  • Using OpenShift routes for exposing services
  • Use HTTPS/TLS for inter services communication
  • Run within the default security policy constraints
2. RHOS Image Certification (For containerized solutions) provides instructions on how to certify container images with RedHat’s certification process. While in some cases the image certification may not be required to be onboarded onto IBM Cloud Pak for Data it is recommended for all containerized workloads being deployed into a RHOS cluster.

2. Install/Deployment Instructions

This section provides detailed information on how to deploy the application on a Cloud Pak for Data cluster (Including details on any dependency installation steps).
Example:
1. Download the helm chart / Operator from the link. (The application / helm chart is going to be hosted on the IBM partner's infrastructure).
2. Authenticate with OpenShift API server using:
oc login -u <username> -p <password> https://open-shift-api-server;
3. Create a new project
oc new-project <project-name> --description=<project-description>
4. Configure the helm utility and deploy the helm chart into the new project <namespace> created using the oc utility above.
helm install -name <deployment-name> --namespace <project-name> --tls <helm-chart>
5. Create routes to expose the application.
oc project <project-name>;
oc get services;
oc expose service <service-name>;
oc get route
6. To open the application, either use the displayed route in the above command or use the add-on tile's ‘OpenUrl’ link.
Notes:
  • You can use screenshots to better describe how to deploy and launch the application
  • For a standalone install, provide instructions on: downloading the docker images, loading the images to the local docker registry, and any modifications to be done to the helm charts to deploy.

3. Uninstall/Reinstall instructions

This section provides detailed information on how to uninstall the application and also backup/restore data from/to the application on a Cloud Pak for Data cluster.
Example:
1. To uninstall the application using helm, run the following command:
helm delete --purge <deployment_name> --tls
2. To delete the OpenShift project created use the following command:
oc delete project <project_name>
3. To backup data from the application do the following.
4. To restore data after reinstalling please use the following instructions.
5. Use the following instruction to re-install the application on Cloud Pak for Data.

4. Support/Help Documentation

This section provides links and details on support contacts and helm documentation.

5. Sales Support Details

This section provides details on how to contact sales support and information regarding the purchase of the product.

Optional Instruction Sections

Optional instructions provide additional information that may help users take full advantage of your offering:

1. Deployment Workflow

This section explains the deployment workflow at a high-level so the customer will understand the steps involved in deploying the application on Cloud Pak for Data.
2. Application Workflow This section explains the application workflow from the login screen (if any) to a sample use case for the customer to follow to check if the application is working properly.
3. Additional Security Considerations
This section describes any additional security considerations for your application which were not covered by the general security requirements described in the earlier sections (for example, any security exceptions or hardening details that need to be implemented in order for the application to work).

4. Troubleshooting Guide

This section describes the troubleshooting steps for any installation/application error or links to the troubleshooting guide.