Kubernetes
Every deployment is different. Please be aware as you follow these steps that all documented here might not be 100% compatible with your specific configurations.
Some Form.io users may want to utilize the Kubernetes open-source platform to manage their containers. Below is a guide on how to get Kubernetes up and running within your Local Environment.
Pre-requisites
In order to continue will we need a few libraries installed in our terminal to get started.
Installation of kubectl in your terminal application and authenticated against your cluster.
Installation of @formio/deploy CLI in your terminal
Installation of Helm in your terminal application.
After installing Helm you'll want to use it to install the Nginx Ingress Controller onto the cluster. The command displayed in the link should be all you need to achieve this.
OPTIONAL: If you'd like to test out the HPA configuration you'll need to install Metrics Server Repository in order for the HPA configuration to be able to monitor the pods CPU and Memory usage.
Installing Form.io Deploy CLI
To begin the setup of Form.io within a Kubernetes cluster in your local environment, you'll first need to install the @formio/deploy CLI tool. This tool is specifically designed to streamline the deployment process of Form.io on Kubernetes. The repository containing the @formio/deploy CLI, along with detailed installation instructions, is hosted on GitHub. You can access it by visiting clicking the link below.
Please ensure you have followed the provided instructions to install the CLI before proceeding with the deployment process detailed in the subsequent sections. Run the command below to install the CLI.
Create Cluster Ingress Controller
In order to route traffic to our API and PDF server we will want to configure the cluster to include an Ingress Controller. This will vary between Cloud Provider.
The following links are provided to the documentation on creating Ingress Controllers for your varying deploying configurations.
Multi-container Deployment
This deployment assumes you have 1 API server and 1 PDF server associated with your LICENSE_KEY and have a pre-configured Mongo Database Instance and File Storage Provider.
Create Cluster Namespace
Next we will want to create a namespace for our deployment using the kubectl CLI by running the following command.
Kubernetes namespaces provide a mechanism for isolating groups of resources within a single cluster. A namespace is a virtual cluster within a physical cluster, used to divide cluster resources between multiple users and applications. Think of it as a label that provides a scope for names. This allows you to partition resources to manage access control, limit resource consumption, and organize objects such as Pods, Services, and Deployments into a logically named group.
Create and Unzip Deployment Configuration
Now that we've create a deployment zip at our ~/deployments directory we should navigate to this folder, unzip the file and then set some environment variables in the .env of that directory.
Environment Variables
Depending on the cloud service provider your project is utilizing, your .env file—a crucial configuration file that stores environment variables—will need to contain specific variables tailored either for Microsoft Azure or Amazon Web Services (AWS) when it comes to file storage solutions. These variables play a critical role in how your application connects to and interacts with cloud-based file storage services provided by these platforms.
For Form.io API server:
If you followed exactly what was run in previous steps there are really on 5 variables that you need to alter to have the deployment succeed:
LICENSE_KEY: This is your Form.io enterprise license key that is utilized to identify your self-hosted deployments.MONGO: The Mongo compatible NoSQL database string that will be utilized by your Form.io deployment. DO NOT forget to include your database name in your string.
See Azure Storage and AWS S3 Storage examples below to see how these variables should be configured.
For Azure Storage:
If your application is leveraging Azure's cloud services, your .env file will need to include the following environment variables to facilitate the connection to Azure File Storage:
FORMIO_AZURE_CONNECTION_STRING: This key provides your application with the necessary permissions to access your Azure storage account.FORMIO_AZURE_CONTAINER: The name of the container within your Azure storage account where files will be stored.
An example configuration in your .env file for Azure might look like this:
For AWS S3 Storage:
For projects that use AWS for cloud services, the .env file should include details pertinent to accessing AWS S3, a secure, durable, and scalable object storage infrastructure. The required keys include:
FORMIO_S3_KEY: This key identifies your AWS account, granting the necessary access permissions.FORMIO_S3_SECRET: This key acts as the password to your AWS account, and it is used in conjunction with the access key id.FORMIO_S3_BUCKET: The name of the S3 bucket where your files will be stored.FORMIO_S3_REGION: The region of where your S3 bucket resides.
A typical AWS S3 configuration in the .env file might resemble the following:
See AWS Textract Integration for more information on how to configure Textract.
It's vital to ensure that these variables are correctly set and securely stored since they provide direct access to your cloud storage resources. Misconfiguration or exposure of these keys can lead to unauthorized access and potential data breaches. Always follow best practices for security, such as using secrets managers and regularly rotating keys.
Deploy Containers
Note: If you are deploying from Windows would recommend running from Windows Subsystem for Linux (WSL), or run the commands from these scripts individually as these shell scripts are specific to UNIX based operating systems.
Now that you've concluded updating your .env for you configured provider we are ready to deploy our application on to our Kubernetes cluster using Helm. In the scripts folder of the current multicontainer directory we have some pre-made scripts that will assist you with the install, upgrade, and rollback processes.
Remotely Connected Multi-stage API Deployment
This deployment assumes you have 3 API server and 1 PDF server associated with your LICENSE_KEY and have a pre-configured Mongo Database Instance and File Storage Provider.
We will create a single PORTAL_ENABLED API server in our lowest environment then connecting 2 higher level environment API servers to our portal and connecting each of these API servers to a standalone PDF server all running in their own standalone namespaces.
Create Cluster Namespaces
Like we handled in the Multicontainer deployment documentation we want to create namespaces for each of our deployment resources. The difference between this deployment will be that we will create independent namespaces for each of our API server environments as well as our PDF server environment. The intention is to make upgrading & scaling each of these environment isolated and simple to manage.
See Multicontainer deployment documentation for further explanation on Kubernetes namespaces.
Create, Unzip, and Deploy
Each of these commands by default will output a zip file to ~/deployments on your local system. We will be navigating to each of the directory to unzip each of the required resources and this deploying them individually to their respective namespaces.
Note: Would recommend going in the following deployment order as follows:
Deploy PDF server: This will be connected to from EACH of the API server environments. Starting here will limit issues during the deployment process.
Deploy Development API Server (Portal Enabled): This will connect to the PDF server running in its own namespace and also allow you to create the stages that will house the remotely connected servers. Before moving on would validate that PDF server functionality is working correctly.
Deploy Staging API Server (Portal Disabled): Will connect to the PDF server configured through environment variable settings. Then connect to portal using PORTAL_SECRET to its correspond stage as a remotely connected API server. Validate PDF functionality works correctly from portal on this stage.
Deploy Production API Server (Portal Disabled): Repeat the same steps perform for the Staging API server (Step 3). Make sure you used the
formio-prodnamespace as this will define the differentBASE_URLfor this environment.
Last updated
