Skip to main content

Deployment prerequisites

General Kubernetes deployment prerequisites​

Before deploying Cinchy v5 on Kubernetes, you must follow the steps listed below.

Download your tools​

Install the following tools on the machine where the deployment will run:

Create your domains​

All your Cinchy environments will need a domain for each of the following:

  • ArgoCD
  • OpenSearch
  • Grafana

Do this through your specific domain registrar. For example, GoDaddy or Google Domains.

SSL certs​

You must have valid SSL Certs ready when you deploy Cinchy v5. Cinchy recommends using a wildcard certificate if ArgoCD will be exposed via a subdomain. Without the wildcard certificate, you must create a port forward using kubectl on demand to access ArgoCD's portal.

You also have the option to use Self-Signed Certs in Kubernetes deployments. Find more information here.

Secrets management​

Although optional, Cinchy strongly recommends secret management for storing and accessing secrets that you use in the deployment process. Cinchy currently supports the following external secret managers:

The following platform components each require a dedicated secret when external secret management is enabled. Both AWS Secrets Manager and Azure Key Vault use the same naming pattern — the secret name ends with the Cinchy instance name (<cinchy_instance_name>) configured in your deployment.json:

ComponentSecret name
Cinchy Webweb-secret-appsettings-<cinchy_instance_name>
Cinchy IdPidp-secret-appsettings-<cinchy_instance_name> (contains keys: idpsecretappsettings, idpsecretmetadata)
Cinchy Workerworker-secret-appsettings-<cinchy_instance_name>
Cinchy Event Listenerevent-listener-secret-appsettings-<cinchy_instance_name>
Cinchy Connectionsconnections-secret-appsettings-<cinchy_instance_name>
Cinchy Connections Configconnections-secret-config-<cinchy_instance_name>
Meta Formsforms-secret-config-<cinchy_instance_name>
Maintenance CLImaintenance-cli-secret-appsettings-<cinchy_instance_name>
Orchestration AutomationRunnerorchestration-automationrunner-secret-appsettings-<cinchy_instance_name>
Orchestration AutomationRunner Configorchestration-automationrunner-secret-config-<cinchy_instance_name>
Orchestration Scheduler Configorchestration-scheduler-secret-config-<cinchy_instance_name>
Cinchy MCPmcp-secret-appsettings-<cinchy_instance_name>
Cinchy Notificationnotification-secret-appsettings-<cinchy_instance_name>

AWS Secrets Manager — initial setup​

AWS Secrets Manager uses two types of secrets with different structures:

1. Environment settings secret — a single secret named cinchy-environment-settings-<cinchy_instance_name> that holds multiple key-value pairs. Set real values here — the pipeline does not overwrite this secret:

Secret keyValue
encryptionkeyA random 32-byte value as a 64-character hexadecimal string. Set once on initial deployment — do not rotate.
connectionspasswordPassword for the connections@cinchy.com service account.
workerpasswordPassword for the worker@cinchy.com service account.
eventlistenerpasswordPassword for the eventlistener@cinchy.com service account.
maintenancepasswordPassword for the maintenance@cinchy.com service account.
cinchyautomationspasswordPassword for the automations@cinchy.com service account.
notificationpasswordPassword for the notification@cinchy.com service account.
aws secretsmanager create-secret --name cinchy-environment-settings-<cinchy_instance_name> \
  --secret-string '{
    "encryptionkey":"<generate-64-char-hex>",
    "connectionspassword":"<password>",
    "workerpassword":"<password>",
    "eventlistenerpassword":"<password>",
    "maintenancepassword":"<password>",
    "cinchyautomationspassword":"<password>",
    "notificationpassword":"<password>"
  }' \
  --region <your-region>

2. Component secrets — one secret per component, each containing a JSON configuration blob. Use placeholder values on creation — the DevOps pipeline overwrites the content on each run:

aws secretsmanager create-secret --name web-secret-appsettings-<cinchy_instance_name> --secret-string '{"websecretappsettings":"{}"}' --region <your-region>
aws secretsmanager create-secret --name worker-secret-appsettings-<cinchy_instance_name> --secret-string '{"workersecretappsettings":"{}"}' --region <your-region>
aws secretsmanager create-secret --name event-listener-secret-appsettings-<cinchy_instance_name> --secret-string '{"eventlistenersecretappsettings":"{}"}' --region <your-region>
aws secretsmanager create-secret --name connections-secret-appsettings-<cinchy_instance_name> --secret-string '{"connectionssecretappsettings":"{}"}' --region <your-region>
aws secretsmanager create-secret --name connections-secret-config-<cinchy_instance_name> --secret-string '{"connectionssecretconfig":"{}"}' --region <your-region>
aws secretsmanager create-secret --name forms-secret-config-<cinchy_instance_name> --secret-string '{"formssecretconfig":"{}"}' --region <your-region>
aws secretsmanager create-secret --name maintenance-cli-secret-appsettings-<cinchy_instance_name> --secret-string '{"maintenanceclisecretappsettings":"{}"}' --region <your-region>
aws secretsmanager create-secret --name orchestration-automationrunner-secret-appsettings-<cinchy_instance_name> --secret-string '{"orchestrationautomationrunnersecretappsettings":"{}"}' --region <your-region>
aws secretsmanager create-secret --name orchestration-automationrunner-secret-config-<cinchy_instance_name> --secret-string '{"orchestrationautomationrunnersecretconfig":"{}"}' --region <your-region>
aws secretsmanager create-secret --name orchestration-scheduler-secret-config-<cinchy_instance_name> --secret-string '{"orchestrationschedulersecretconfig":"{}"}' --region <your-region>
aws secretsmanager create-secret --name mcp-secret-appsettings-<cinchy_instance_name> --secret-string '{"mcpsecretappsettings":"{}"}' --region <your-region>
aws secretsmanager create-secret --name notification-secret-appsettings-<cinchy_instance_name> --secret-string '{"notificationsecretappsettings":"{}"}' --region <your-region>

If SSO is enabled, also create this secret. It holds both the IDP appsettings and the SAML metadata as separate keys within the same secret:

aws secretsmanager create-secret --name idp-secret-appsettings-<cinchy_instance_name> \
  --secret-string '{"idpsecretappsettings":"{}","idpsecretmetadata":""}' \
  --region <your-region>

Note the ARN returned for each secret (it includes a random 6-character suffix, e.g. …-<cinchy_instance_name>-r0rITk). Add all ARNs to the aws_secrets_manager_arn_list array in your deployment.json so that the Terraform IRSA policy grants the Kubernetes ServiceAccounts read access.

Azure Key Vault — initial setup​

Azure Key Vault secrets are created and updated automatically by the DevOps pipeline on each run using az keyvault secret set. No manual secret creation is required. Ensure the following prerequisites are in place before running the pipeline:

  • The Azure Key Vault resource exists and is referenced in your deployment.json (key_vault_name).
  • The AKS managed identity or service principal has get, list, and set permissions on the Key Vault.
  • key_vault_secrets_provider_enabled is set to "true" in your deployment.json.

For full secrets setup instructions, see:

Single sign-on​

If you would like to set up single sign-on for use in your Cinchy v5 environments, please review the SSO integration page.

Docker images​

You can use Cinchy Docker images or your own. If you would like to use Cinchy images, please follow This section to access them.

Access Cinchy Docker images​

You will pull Docker images from Cinchy's AWS Elastic Container Registry (ECR).

To gain access to Cinchy's Docker images, you need login credentials to the ECR. Contact Cinchy Support for access.

Create your repositories​

You must create the following four Git repositories. You can use any source control platform that supports Git, such as Gitlab, Azure DevOps, or GitHub.

  • cinchy.terraform: Contains all Terraform configurations.
  • cinchy.argocd: Contains all ArgoCD configurations.
  • cinchy.kubernetes: Contains cluster and application component deployment manifests.
  • cinchy.devops.automations: Contains the single configuration file and binary utility that maintains the contents of the above three repositories.
caution

You must have a service account with read/write permissions to the git repositories created above.

Access to Cinchy artifacts​

You will need to access and download the Cinchy artifacts before deployment.

To access the Kubernetes artifacts:

  1. Access the Cinchy Releases table. Please contact Cinchy Support if you don't have the access credentials necessary.
  2. Navigate to the release you wish to deploy.
  3. Download the .zip file(s) listed under the Kubernetes Artifacts column.
  4. Check the contents of each of the directories into their respective repository.
caution

Please contact Cinchy Support if you are encountering issues accessing the table or the artifacts.

Kubernetes Azure requirements​

If you are deploying Cinchy v5 on Azure, you require the following:

Terraform requirements​

  • A resource group that will contain the Azure Blob Storage with the terraform state.
  • A storage account and container (Azure Blob Storage) for persisting terraform state.
  • Install the Azure CLI on the deployment machine. It must be set to the correct profile/login

Subnet sizing (applies to all Azure deployments)​

A single subnet with sufficient IP address capacity is required regardless of whether you use an existing or new resource group. With Azure CNI, subnet usage includes both node IPs and pod IP capacity per node (based on maxPods). You must also size for upgrade surge: during a rolling node pool upgrade, AKS provisions a new surge node before draining the old one, temporarily requiring capacity for more nodes than your steady-state count.

The max-node estimates below assume maxPods=250 and include node IPs (max nodes ≈ usable IPs / (maxPods + 1)). If your cluster uses a different maxPods value, recalculate these limits accordingly.

Subnet CIDRUsable IPsMax nodes (steady-state, assumes maxPods=250)Suitable for rolling upgrades?
/22~1,019~4No — fails at max scale
/21~2,043~8Marginal
/20~4,091~16Yes (minimum recommended)
/19~8,187~32Yes (recommended)

The minimum recommended subnet is /20 (4,096 IPs). The deployment template (azure.json) defaults to /19 (8,192 IPs), which provides comfortable headroom for autoscaling and upgrades. Do not use /22 or smaller — this is insufficient for rolling AKS upgrades. See the AKS upgrade guide for the full sizing rationale.

  • Existing resource group: Create the subnet with the appropriate CIDR before deployment.
  • New resource group: Terraform provisions the subnet automatically using the subnet_prefix value in your azure.json. Verify this value meets the sizing requirements above before running Terraform.

The deployment template has two options available:

  • Use an existing resource group.
  • Creating a new one.

Existing resource group​

If you prefer an existing resource group, you must provision the following before the deployment:

New resource group​

  • If you prefer a new resource group, all resources will be automatically provisioned.
  • The quota limit of the Total Regional vCPUs and the Standard DSv3 Family vCPUs (or equivalent) must offer enough availability for the required number of vCPUs (minimum of 24).
  • An AAD user account to connect to Azure, which has the necessary privileges to create resources in any existing resource groups and the ability to create a resource group (if required).

Kubernetes AWS requirements​

If you are deploying Cinchy v5 on AWS, you require the following:

Terraform requirements:​

  • An S3 bucket that will contain the terraform state.
  • Install the AWS CLI on the deployment machine. It must be set to the correct profile/login

The template has two options available:

  • Use an existing VPC.
  • Create a new one.

Existing VPC​

  • If you prefer an existing VPC, you must provision the following before the deployment:
    • The VPC. It's important that the address range be enough for all executing processes within the cluster, such as a CIDR ending with /21 to provide a range of 2048 IPs.
    • 3 Subnets (one per AZ). It's important that the address range be enough for all executing processes within the cluster, such as a CIDR ending with /23 to provide a range of 512 IPs.
    • If the subnets are private, a NAT Gateway is required to enable node group registration with the EKS cluster.

New VPC​

  • If you prefer a new VPC, all resources will be automatically provisioned.
  • The limit of the Running On-Demand All Standard vCPUs must offer enough availability for the required number of vCPUs (minimum of 24).
  • An IAM user account to connect to AWS which has the necessary privileges to create resources in any existing VPC and the ability to create a VPC (if required).
  • You must import the SSL certificate into AWS Certificate Manager, or a new certificate can be requested via AWS Certificate Manager.
  • If you are importing it, you will need the PEM-encoded certificate body and private key. You can find this, you can get the PEM file from your chosen domain provider (GoDaddy, Google, etc.) Read more on this here.

IIS deployment prerequisites​

Before deploying Cinchy v5 on IIS, you require the following:

Access the artifacts​

You need to access and download the Cinchy binary before deployment:

caution

Please contact Cinchy Support if you are encountering issues accessing the table or the artifacts.

Prerequisites​

The following prerequisites are required to deploy the core platform, Connections, and the Worker/Listener.

Minimum system requirements​

caution
  • Cinchy v5.13+ uses .NET 8.
  • v5.4 - v5.12 use .NET 6.0.
  • v4.18.0 - v5.3 use .NET Core 3.1.

Minimum hardware requirements​

  • 2 x 2 Ghz Processor
  • 8-16GB Ram

Minimum database server hardware recommendations​

  • 4 × 2 GHz Processor
  • 24-32 GB RAM
  • Hard disk storage dependent upon use case. Cinchy maintains historical versions of data and performs soft deletes which will add to the storage requirements.

Clustering​

Clustering considerations are applicable to both the Web and Database tiers in the Cinchy deployment architecture.

The web tier can be clustered by introducing a load balancer and scaling web server instances horizontally. Each node within Cinchy uses an in-memory cache of metadata information, and expiration of cached elements is triggered upon data changes that would impact that metadata. Data changes processed by one node wouldn't be known to other nodes without establishing connectivity between them. The nodes must be able to communicate over either HTTP or HTTPS through an IP based binding on the IIS server that allows the broadcast of cache expiration messages. The port used for this communication is different from the standard port that's used by the application when a domain name is involved. Often for customers this means that a firewall port must be opened on these servers.

The database tier relies on standard MS SQL Server failover clustering capabilities.

Scaling considerations​

The web application oversees all interactions with Cinchy be it through the UI or connectivity from an application. It interprets/routes incoming requests, handles serialization/deserialization of data, data validation, enforcement of access controls, and the query engine to transform Cinchy queries into the physical representation for the database. The memory footprint for the application is low, as caching is limited to metadata, but CPU use grows with request volume and complexity(For example, insert/update operations are more complex than select operations). As the user population grows or request volume increases, there may be a need to add nodes.

The database tier relies on a persistence platform that scales vertically. As the user population grows and request volume increases, the system may require additional CPU / Memory. Cinchy recommends you start off in an environment that allows flexibility (such as a VM) until you can profile the real-world load and establish a configuration. On the storage side, Cinchy maintains historical versions of records when changes are made and performs soft deletes of data which will add to the storage requirements. The volume of updates occurring to records should be considered when estimating the storage size.

Backups​

Outside of log files there is no other data generated & stored on the web servers by the application, which means backups are centered around the database. Since the underlying persistence platform is a MS SQL Server, this relies on standard procedures for this platform.