1. Overview

There are various things to consider before deploying Cinchy v5.

The pages in this Deployment Planning section will guide you through the considerations you should think about and the prerequisites that you should implement before deploying version 5 of the Cinchy platform.

The pages in this section include:

• Deployment Architecture Overview: This page explores your two high-level options for deploying Cinchy, on Kubernetes or on VM, and why we recommend a Kubernetes deployment. It also walks you through the important decision of selecting a database to run your deployment on, as well as some sizing considerations.

  • Kubernetes Deployment Architecture: This page provides Infrastructure (for both Azure and AWS), Cluster, and Platform component overviews for Kubernetes deployments. It also guides you through considerations concerning your cluster configuration.

  • IIS Deployment Architecture: This page provides Infrastructure and Platform component overviews for IIS (VM) deployments.

• Deployment Prerequisites: This page details important prerequisites for deploying Cinchy v5.

2. Deployment Planning Checklist

We have provided the following checklist for you to use when planning for your Cinchy v5 deployment. Each item is linked to the appropriate documentation page to provide more insight and clarity.

• Will you run on Kubernetes or a VM?

WIndows IIS vs Kubernetes

Kubernetes is an open-source system that manages and automates the full lifecycle of container-based applications. You now have the ability to deploy Cinchy v5 on Kubernetes, and with it comes a myriad of features that help to simplify your deployment and enhance your scaling. Kubernetes can maximize your container capacity and easily scale up/down with your current operations.

You also have the option to run Cinchy on Microsoft IIS, which was the traditional deployment method prior to Cinchy v5. Internet Information Services (IIS) for Windows Server is a flexible, secure and manageable Web server for hosting anything on the Web.

We recommend using Kubernetes to deploy Cinchy v5, because of the robust features that you can leverage, such as improved logging and metrics. Using Kubernetes allows for a greater ability to scale your Cinchy instances as well as the ability to lower your costs by using PostgreSQL.

The main differences between a Kubernetes based deployment and an IIS deployment are:

If you will be running on Kubernetes, please review the following checklist:

• Which database will you use?

• Define your sizing.

• Define your cluster configuration.

• How many clusters will you need?

  • Will you be sharing from an existing cluster?

  • Will you be running multiple environments on a single cluster?

  • Will you be using Cinchy's recommended cluster components or your own?

• Define your object storage requirements.

  • Create an S3 compatible bucket.

• Create your SSL Certs (With the option to use Self-Signed).

• Define your Secrets Management, if desired.

• Define whether you will use Cinchy's Docker Images or your own.

  • If using Cinchy’s, pull the images.

• Access the deployment repositories and copy them into your own repo (Github or similar).

If you will be running on IIS, please review the following checklist:

• Ensure that you have an instance of SQL Server 2017+

• Ensure that you have a Windows Server 2012+ machine with IIS 7.5+ installed

• Install .net core Hosting bundle Version 6.0

  • Specifically, install: ASP.NET Core/.NET Core Runtime & Hosting Bundle

• Ensure that you review the minimum web server hardware recommendations

• Ensure that you review the minimum database server hardware recommendations

• Define your application storage requirements.

• Ensure you have access to the release binary.

1. How to Enable TLS 1.2

1. Navigate to the CinchySSO Folder > appsettings.json file.

2. Find the following line:

3. Replace the above line with the following:

4. Navigate to the Cinchy Folder > web.config file.

5. Find the following line:

6. Replace the above line with the following:

7. You may need to restart the application pools in IIS for the changes to take effect.

1. Overview

Cinchy supports integration with any Identity Provider that issues SAML tokens (e.g. Active Directory Federation Services) for authenticating users.

It follows an SP Initiated SSO pattern where the SP will Redirect to the IdP and the IdP must submit the SAML Response via an HTTP Post to the SP Assertion Consumer Service.

Below is a diagram outlining the flow when a non-authenticated user attempt to access a Cinchy resource (Image 1).

2. Configure SAML Authentication - IIS Deployments

Cinchy must be registered with the Identity Provider. As part of that process you'll supply the Assertion Consumer Service URL, choose a client identifier for the Cinchy application, and generate a metadata XML file.

The Assertion Consumer Service URL for Cinchy is the base URL for the CinchySSO application followed by "{AcsURLModule}/Acs"

e.g. https:///<CinchySSO URL>/Saml2/Acs

e.g. https://myCinchyServer/Saml2/Acs

To enable SAML authentication within Cinchy, follow the below steps:

1. You can find the necessary metadata XML from the applicable identity provider you're using the login against. Place the metadata file in the deployment directory of the CinchySSO web application.

2. Update the values of the below app settings in the CinchySSO appsettings.json file.

• SAMLClientEntityId - The client identifier chosen when registering with the Identity Provider

• SAMLIDPEntityId - The entityID from the Identity Provider metadata XML

• SAMLMetadataXmlPath - The full path to the metadata XML file

• AcsURLModule - This parameter is needs to be configured as per your SAML ACS URL. For example, if your ACS URL looks like this "https:///<CinchySSO URL>/Saml2/Acs", then the value of this parameter should be "/Saml2"

Once SSO is enabled, the next time a user arrives at the Cinchy login screen they will see an additional button for "Single Sign-On".

3. Configure SAML Authentication - Kubernetes Deployments

1. Retrieve your metadata.xml file from the identity provider you're using the login against.

2. Navigate to your cinchy.kubernetes\environment_kustomizations_template\instance_template\idp\kustomization.yaml file.

3. Add your metadata.xml patch into your secrets where specified below as <<metadata.xml>>

4. Navigate to your devops.automation > deployment.json in your Cinchy instance.

5. Add the following fields into the .json and update them below using the metadata.xml.

6. Navigate to your kubernetes\environment_kustomizations_template\instance_template_encoded_vars\idp_appsettings_json.

7. Update the below code with your proper AppSettings and ExternalIdentityClaimSection details.

8. Run devops automation script which will populate the updated outputs into the cinchy.kubernetes repo.

9. Commit your changes and push to your source control system.

10. Navigate to your ArgoCD dashboard and refresh the idp-app to pick up your changes. It will also delete your currently running pods in order to pick up the latest secrets.

11. Once the pods are healthy, you can verify the changes by looking for the SSO Tab on your Cinchy login page.

4. User Management

Before a user is able to login through the SSO flow, the user must be set up in Cinchy with the appropriate authentication configuration.

Users in Cinchy are maintained within the Users table in the Cinchy domain. Each user in the system is configured with 1 of 3 Authentication Methods:

• Cinchy User Account - These are users that are created and managed directly in the Cinchy application. They log into Cinchy by entering their username and password on the login screen.

• Non Interactive - These accounts are intended for application use.

• Single Sign-On - These users authenticate through the SSO Identity Provider (configured using the steps above). They log into Cinchy by clicking the "Login with Single Sign-On" link on the login screen.

4.1 How to define a new SSO User

Create a new record within the Users table with the Authentication Method set to "Single Sign-On".

4.2 How to convert an existing user to SSO User

Change the Authentication Method of the existing user to "Single Sign-On".

4.3 Logging in with SSO

Once a user is configured for SSO, they can then click the "Login with Single Sign-On" link on the login page and that will then take them through the Identity Provider's authentication flow and bring them into Cinchy.

5. Automatic User Creation - IIS Deployments

Once SSO has been enabled on your instance of Cinchy, by default, any user that does not exist in the Cinchy Users table will not be able to login regardless if they are authenticated by the Identity Provider.

Enabling Automatic User Creation means that upon login, if the Identity Provider authorizes the user, an entry for this user will automatically be created in the Cinchy Users table if one does not already exist. This means that any SSO authenticated user is guaranteed to be able to access the platform.

See below for details on how to enable Automatic User Creation.

5.1 Prerequisites for Automatic User Creation

The Identity Provider configuration must include the following claims in addition to the base configuration in the SAML token response:

• First Name

• Last Name

• Email

In order to enable automatic group assignment for newly created users (which is applicable if you plan on using AD Groups), then you must also include an attribute that captures the groups that this user is a member of (e.g. memberOf field in AD)

5.2 Configuration Setup

Enabling automatic user creation requires the following changes. For IIS Deployments this will be done to the appsettings.json file in the CinchySSO web application.

1. Add ExternalClaimName attribute values under "ExternalIdentityClaimSection" in appsettings.json file. Do not add the value for "MemberOf" if you don't want to enable automatic group assignment .

2. The ExternalClaimName value must be updated to create a mapping between the attribute name in the SAML response and the required field. (e.g. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname is the name in the SAML response for the FirstName field)

6. Further Reading

Table of Contents

1. Component Diagram

The below diagram shows a high level overview of Cinchy's Infrastructure components when deploying on IIS.

2. Component Overview

Introduction

This section of Cinchy's documentation will guide you through the deployment process for Cinchy version 5: from planning all the way through to installation and upgrades.

• If you are looking to deploy Cinchy v5, please start here and read through all the sub-pages:

  • Once you have familiarized yourself with the above documentation, you may move on to either of the below guides, depending on your preference:

• If you are a customer currently on v4 and want to upgrade to v5, start here:

If you have any questions about the processes outlined in this section, please reach out to our Support team:

• Via email: support@cinchy.com

• Via phone: 1-888-792-6051

• Through the support portal:

Table of Contents

1. Infrastructure Configuration (On Cluster)

The below diagram shows a high level overview of a possible Infrastructure diagram with components on the cluster, however your specific configuration may vary (Image 1).

2. AWS Infrastructure Configuration (Outside Cluster)

When deploying Cinchy version 5 on Kubernetes, you may deploy via Amazon Web Services (AWS). The below diagram shows a high level overview of a possible AWS Infrastructure with components outside the cluster, however your specific configuration may vary (Image 2).

2.1 Infrastructure Component Overview

3. Azure Infrastructure Configuration (Outside Cluster)

When deploying Cinchy version 5 on Kubernetes, you may deploy via Microsoft Azure. The below diagram shows a high level overview of possible Azure Infrastructure with components outside the cluster, however your specific configuration may vary (Image 3).

3.1 Infrastructure Component Overview

4. Cluster Level Component Overview

The following highlighted area provides a high-level overview of cluster level components used when deploying Cinchy on Kubernetes, as well as what versions they are running.

These are created once per cluster. Clients may choose to run these components outside of the cluster or replace with their own comparable components. This diagram shows them in the cluster (Image 4).

Cluster Level Components

These are created once per cluster. Clients may choose to run these components outside of the cluster or replace with their own comparable components.

4.1 Cluster Configuration

There are a few things to consider about your cluster configuration before you deploy Cinchy on Kubernetes:

• How many clusters will you need?

• Will you be sharing from an existing cluster?

• Will you be running multiple environments on a single cluster?

5. Instance Component Overview

Each instance of Cinchy has the following components, which are used to either provide an experience to users/applications or connect data in/out of Cinchy. Since multiple Cinchy instances can be deployed per cluster, these components will repeat for each environment.

The following highlighted area provides a high-level overview of instance level components used when running Cinchy on Kubernetes (Image 5).

• Connections: The Cinchy Connections experience is used to help easily create data syncs in/out of the platform. It features persistent storage.

• Data Browser: Cinchy’s Dataware platform features a Universal Data Browser that allows users to view, change, analyze, and otherwise interact with all data on the network. The Data Browser even enables non-technical business users to manage and update data, build models, and set controls, all through an easy and intuitive UI.

• Identity Provider: An Identity Provider (IdP) creates and manages user credentials and associated identity attributes. IdPs authentication services are used in Cinchy to authenticate end-users.

6. GitOps

Once you configurations are set, ArgoCD automates the deployment of the desired application states into your specified target environments. Implemented as a Kubernetes controller, it continuously monitors running applications and compares the current, live state against the desired target state (as specified in your repositories).

Overview

Beginning in Cinchy v5.6, you are now able to run the Connections pod under a service account that uses an AWS IAM (Identity and Access Management) role, which is an IAM identity that you can create to have specific permissions and access to your AWS resources. To set up AWS IAM role authentication, please review the procedure below.

1. AWS IAM Role Authentication

1. To check that you have an OpenID Connect set up with the cluster (the default for deployments made using the Cinchy automation process), run the below command within a terminal:

aws eks describe-cluster --name <CLUSTER_NAME> --query "cluster.identity.oidc.issuer"

1. The output should appear like the below. Make sure to note this down for later use.

https://oidc.eks.<REGION>.amazonaws.com/id/<OIDC_ID>

1. Log in to your AWS account and create an IAM Role policy through the AWS UI. Ensure that it has S3 access.

2. Run the below command in a terminal to create a service account with the role created in step 3. If your cluster has a special character like an underscore, skip to section 1.1.

eksctl create iamserviceaccount --name my-service-account --namespace default --cluster my-cluster --role-name "my-role" --attach-policy-arn arn:aws:iam::111122223333:policy/my-policy --approve

1.1 Cluster Names with Special Characters

If your cluster name has a special character, like an underscore, you will need to create and apply the yaml. Follow section 1 up until step 4, and then follow the below procedure.

1. In an editor like Visual Code or similar, create a new file titled "my-service-account.yaml" in your working directory. It should contain the below content.

/apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-service-account
  namespace: default

1. In a terminal, run the below command:

kubectl apply -f my-service-account.yaml -n <namespace>

1. In an editor like Visual Code or similar, create a new file titled "trust-relationship.json" in your working directory. It should contain the below content.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::$account_id:oidc-provider/$oidc_provider"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "$oidc_provider:aud": "sts.amazonaws.com",
          "$oidc_provider:sub": "system:serviceaccount:$namespace:$service_account"
        }
      }
    }
  ]
}

For example,

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::204393242335:oidc-provider/oidc.eks.ca-central-1.amazonaws.com/id/8A024CF24ADD3925BEFA224C4BDD005B"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "oidc.eks.ca-central-1.amazonaws.com/id/8A024CF24ADD3925BEFA224C4BDD005B:aud": "sts.amazonaws.com",
                    "oidc.eks.ca-central-1.amazonaws.com/id/8A024CF24ADD3925BEFA224C4BDD005B:sub": "system:serviceaccount:devops-aurora-1:connections-serviceaccount-s3"
                }
            }
        }
    ]
}

1. Execute the following command to create the role, referencing the above .json file:

aws iam create-role --role-name my-role --assume-role-policy-document file://trust-relationship.json --description "my-role-description"

For example,

aws iam create-role --role-name connections-role-test --assume-role-policy-document file://trust-relationship.json --description "testing sa role for pod"

1. Execute the following command to attach the IAM policy to your role:

aws iam attach-role-policy --role-name my-role --policy-arn=arn:aws:iam::$account_id:policy/my-policy

For example,

aws iam attach-role-policy --role-name connections-role-test --policy-arn=arn:aws:iam::aws:policy/AmazonS3FullAccess

1. Execute the following command to annotate your service account with the Amazon Resource Name (ARN) of the IAM role that you want the service account to assume:

kubectl annotate serviceaccount -n $namespace $service_account eks.amazonaws.com/role-arn=arn:aws:iam::$account_id:role/my-role

For example,

kubectl annotate serviceaccount -n devops-aurora-1 connections-serviceaccount-s3 eks.amazonaws.com/role-arn=arn:aws:iam::204393242335:role/connections-role-test

1. Confirm that the role and service account are configured correctly by verifying the ouput of the following commands:

aws iam get-role --role-name my-role --query Role.AssumeRolePolicyDocument
aws iam get-role --role-name connections-role-test --query Role.AssumeRolePolicyDocument

1.2 Authorizing for Data Syncs

To ensure that the Connections pod's role has the correct permissions, the role specified by the user in AWS must have its Trusted Relationships configured as such:

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Principal": {
				"AWS": "<role-arn-created-above>",
				"Service": "s3.amazonaws.com"
			},
			"Action": "sts:AssumeRole"
		}
	]
}

1.3 Confirmation

To confirm that the Connections app is using the service account:

1. Navigate to the cinchy.kubernetes repo > connections/kustomization.yaml file

2. Execute the following:

- op: replace
      path: /spec/template/spec/serviceAccountName
      value: connections-serviceaccount-s3

1. From a terminal, run the below command:

kubectl describe deployment connections-app -n <namespace>

1. The output should look like the following:

Table of Contents

1. Group Management

This section defines how to manage Groups.

1.1 Cinchy Groups

Cinchy Groups are containers that have Users and other Groups within them as members. They are used to provision access controls throughout the platform. Cinchy Groups enable centralized administration for access controls.

Groups are defined in the "Groups" table within the Cinchy domain. By default this table can only be managed by members of the Cinchy Administrators group. Each group has the following attributes:

1.2 How to Define a New AD Group

1. To define a new AD Group, create a new record within the Groups Table with the same name as the AD Group (using the cn attribute).

2. Set the Group Type to "AD Group".

1.3 How to Convert an Existing Group to Sync with AD

1. To convert an existing group, update the Name attribute of the existing group record to match the AD Group (using the cn attribute).

2. Set the Group Type to "AD Group".

2. Group Membership Sync

AD Groups defined in Cinchy have their members synced from AD through a batch process that leverages the Cinchy Command Line Interface (CLI).

2.1 Execution Flow

The sync operation performs the following high-level steps:

1. Fetches all Cinchy registered AD Groups using a Saved Query.

2. Retrieves the usernames of all members for each AD Group. The default attribute for username that is retrieved is "userPrincipalName", but configurable as part of the sync process.

3. For each AD Group, it loads the users that are both a member in AD and exist in the Cinchy Users table (matched on the Username) into the "Users" attribute of the Cinchy Groups table.

2.2 Dependencies

1. The Cinchy CLI Model must be installed in your instance of Cinchy. See here for more details.

2. An instance of the Cinchy CLI must be available to execute the sync.

3. A task scheduler is required to perform the sync on a regular basis (e.g. Autosys).

2.3 Configuration Steps

2.3.1 Create a Saved Query to retrieve AD Groups from Cinchy

1. Create a new query within Cinchy with the below CQL to fetch all AD Groups from the Groups table. The domain & name assigned to the query will be referenced in the subsequent step.

SELECT [Name]
FROM [Cinchy].[Cinchy].[Groups]
WHERE [Group Type] = 'AD Group' 
AND [Deleted] IS NULL

2.3.2 Create the Sync Config

1. Copy the below XML into a text editor of your choice and update the attributes listed in the table below the XML to align to your environment specific settings.

2. Once complete, create an entry with the config in your Data Sync Configurations table (part of the Cinchy CLI model).

<?xml version="1.0" encoding="utf-16" ?>
<BatchDataSyncConfig name="AD_GROUP_SYNC" version="1.0.0" xmlns="http://www.cinchy.co">
  <Parameters />
  <LDAPDataSource objectCategory="group" ldapserver="LDAP:\\activedirectoryserver.domain.com" username="encryptedUsername" password="encryptedPassword" >
    <Schema>
      <Column name="cn" ordinal="1" dataType="Text" maxLength="5000" isMandatory="false" validateData="false" trimWhitespace="true" description=""/>
      <Column name="member.userPrincipalName" ordinal="2" dataType="Text" maxLength="200" isMandatory="false" validateData="false" trimWhitespace="true" description=""/>
    </Schema>
    <Filter>
      lookup('Domain Name','Query Name')
    </Filter>
  </LDAPDataSource>
  <CinchyTableTarget model="" domain="Cinchy" table="Groups" suppressDuplicateErrors="false">
    <ColumnMappings>
      <ColumnMapping sourceColumn="cn" targetColumn="name" />
      <ColumnMapping sourceColumn="member.userPrincipalName" targetColumn="Users" linkColumn="Username" />
    </ColumnMappings>
    <SyncKey>
      <SyncKeyColumnReference name="name" />
    </SyncKey>
	<ChangedRecordBehaviour type="UPDATE" />
    <DroppedRecordBehaviour type="IGNORE" />
  </CinchyTableTarget>
</BatchDataSyncConfig>

2.3.3 Sync Execution & Scheduling

1. The below CLI command (see here for additional information on the syncdata command) should be used to execute the sync.

2. Update the command parameters (described in the table below) with your environment specific settings.

3. Execution of this command can be scheduled at your desired frequency using your scheduler of choice.

dotnet Cinchy.CLI.dll syncdata -s cinchyAppServer -u username -p "encryptedPassword" -m "Model" -f "AD_GROUP_SYNC" -d "TempDirectory" 

Parameters

3. High Number of Groups in ADFS

If you are syncing someone with a lot of ADFS groups, the server may reject the request for the header being too large. If you are able to login as a user with a few groups in ADFS but run into an error with users with a lot of ADFS groups (regardless of if those ADFS groups are in Cinchy), you will need to make the following changes:

3.1 Update the Server Max Request Header Size

1. Follow the instructions outlined in this document.

3.2 CinchySSO App Settings

1. In your CinchySSO app settings, you will also need to increase the max size of the request, as follows:

"AppSettings": {
  ...
  "MaxRequestHeadersTotalSize": {max size in bytes},
  "MaxRequestRequestBufferSize": {max size in bytes, use same as above},
  "MaxRequestBodySize": -1
}

Table of Contents

1. Introduction

This page details the instructions for deployment of Cinchy v5 on Kubernetes. We recommend, and have documented below, that this is done via Terraform and ArgoCD. This setup involves a utility to centralize and streamline your configurations.

The Terraform scripts and instructions provided enable deployment on Azure and AWS cloud environments.

2. Deployment Prerequisites

The following lists are required prerequisites for installing Cinchy v5 on Kubernetes.

Note that some prerequisites will depend on whether you are deploying on Azure or on AWS.

2.1 All Platforms

These prerequisites apply whether you are installing on Azure or on AWS.

• The following four Git repositories must be created. Any source control platform supporting Git may be used, e.g. Gitlab, Azure DevOps, Github

  • cinchy.terraform: This repo contains all Terraform configurations.

  • cinchy.argocd: This repo contains all ArgoCD configurations.

  • cinchy.kubernetes: This repo contains cluster and application component deployment manifests.

  • cinchy.devops.automations: This repo contains the single configuration file and binary utility that maintains the contents of the above three repositories.

• Download the artifacts for the four Git repositories. See here for information on accessing these. Check the contents of each of the directories into the respective repository.

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

• The following tools should be installed on the machine where the deployment will run:

  • Terraform

    • For an introductory guide on Terraform + AWS, see here

    • For an introductory guide on Terraform + Azure, see here

  • Kubectl (v1.23.0+)

  • .NET Core 3.1.x

  • Bash (Git Bash may be used on Windows)

• If you are using Cinchy's docker images, pull them.

• You will need a single domain for accessing ArgoCD, Grafana, Opensearch Dashboard, and any deployed Cinchy instances. There are two routing options for accessing these applications - path based or subdomains. See below for an example with multiple cinchy instances:

• You will need an SSL certificate for the cluster. This should be a wildcard certificate if you will use subdomain based routing. You can also use Self-Signed SSL.

2.2 Azure Deployment

The following prerequisites are required if you are deployment Cinchy v5 on Azure.

• Terraform Backend 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.

• The Azure CLI should be installed on the machine where the deployment will be run. It must be set to the correct profile/login

• The deployment template has the option of either leveraging an existing resource group or creating a new one:

  • If an existing resource group is preferred, the prerequisite requires the following be provisioned in advance of the deployment:

    • The resource group.

    • A VNet within the resource group.

    • A single subnet. It's important that the address range be sufficient for all executing processes within the cluster, e.g. a CIDR ending with /22 to provide a range of 1024 IPs.

  • If a new resource group is preferred, all resources will be automatically provisioned.

• The quota limit of the Total Regional vCPUs and the Standard DSv3 Family vCPUs (or equivalent) must provide sufficient 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).

2.3 AWS Deployment

The following prerequisites are required if you are deployment Cinchy v5 on AWS.

• Terraform Backend Requirements:

  • An S3 bucket that will contain the terraform state.

• The AWS CLI should be installed on the machine where the deployment will be run. It must be set to the correct profile/login

• The template has the option of either leveraging an existing VPC or creating a new one:

  • If an existing VPC is preferred, the prerequisite requires the following be provisioned in advance of the deployment:

    • The VPC. It's important that the address range be sufficient for all executing processes within the cluster, e.g. 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 sufficient for all executing processes within the cluster, e.g. 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.

  • If a new VPC is preferred, all resources will be automatically provisioned.

• The limit of the Running On-Demand All Standard vCPUs must provide sufficient 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).

• The SSL certificate must be imported into AWS Certificate Manager, or a new certificate can be requested via AWS Certificate Manager.

  • If your 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.

3. Initial Configuration

The following steps detail the instructions for setting up the initial configurations.

3.1 Configure the Deployment.json

1. Navigate to your cinchy.devops.automations repository where you will see an aws.json and azure.json.

2. Depending on the cloud platform that you are deploying to, select the appropriate file and copy it into a new file named deployment.json (or <cluster name>.json) within the same directory.

3. This file will contain the configuration for the infrastructure resources and the Cinchy instances to deploy. Each property within the configuration file has comments in-line describing its purpose along with instructions on how to populate it.

4. Follow the guidance within the file to configure the properties.

5. Commit and push your changes.

3.2 Execute cinchy.devops.automations

This utility updates the configurations in the cinchy.terraform, cinchy.argocd, and cinchy.kubernetes repositories.

1. From a shell/terminal, navigate to the cinchy.devops.automations directory location and execute the following command:

dotnet Cinchy.DevOps.Automations.dll "deployment.json"

2. If the file created in "Configuring the Deployment.json" step 2 has a name other than "deployment.json", the reference in the command will will need to be replaced with the correct name of the file.

3. The console output should terminate with a "Completed successfully".

4. Terraform Deployment

The following steps detail how to deploy Terraform.

Cinchy.terraform Repo Structure - AWS

If deploying on AWS: Within the Terraform > AWS directory, a new folder named eks_cluster is created. Nested within that is a subdirectory with the same name as the newly created cluster.

To perform terraform operations, the cluster directory must be the working directory during execution. This applies to everything within step 4 of this guide.

Cinchy.terraform Repo Structure - Azure

If deploying on Azure: Within the Terraform > Azure directory, a new folder named aks_cluster is created. Nested within that is a subdirectory with the same name as the newly created cluster.

To perform terraform operations, the cluster directory must be the working directory during execution.

4.1 Cloud Provider Authentication

1. Launch a shell/terminal with the working directory set to the cluster directory within the cinchy.terraform repo.

2. If you are using AWS, run the following commands to authenticate the session:

export AWS_DEFAULT_REGION=REGION
export AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY_ID
export AWS_SECRET_ACCESS_KEY=YOUR_ACCESS_KEY

3. If using Azure, run the following command and follow the on screen instructions to authenticate the session:

az login

4.2 Deploy the Infrastructure

1. Execute the following command to create the cluster:

bash create.sh

2. Type yes when prompted to apply the terraform changes.

The resource creation process can take approx. 15-20 minutes. At the end of the execution there will be a section with the following header

======= Output Variables =======

If deploying on AWS, this section will contain 2 values: Aurora RDS Server Host and Aurora RDS Password

If deploying on Azure, this section will contain a single value: Azure SQL Database Password

These variable values are required to update the connection string within the deployment.json file (or equivalent) in the cinchy.devops.automations repo.

4.3 Retrieve the SSH Keys

The following section breaks down how to retrieve your SSH keys for both AWS and Azure deployments.

4.3.1 AWS SSH Keys

1. The SSH key to connect to the Kubernetes nodes is maintained within the terraform state and can be retrieved by executing the following command:

terraform output -raw private_key

4.3.2 Azure SSH Keys

1. The SSH key is output to the directory containing the cluster terraform configurations.

5. Update the Deployment.json

The following section pertains to updating the Deployment.json file.

5.1 Update the Database Connection String

1. Navigate to the the deployment.json (created in step 3.1) > cinchy_instance_configs section.

2. Each object within represents an instance that will be deployed on the cluster. Each instance configuration contains a database_connection_string property. This has placeholders for the host name and password that must be updated using output variables from the previous section.

5.2 Create the IAM User for S3 (AWS Only)

The terraform script will create an S3 bucket for the cluster that must be accessible to the Cinchy application components.

To access this programmatically, an IAM user that has read/write permissions to the new S3 bucket is required. This can be an existing user.

The Access Key and Secret Access Key for the IAM user must be specified under the object_storage section of the deployment.json

5.3 Update Blob Storage Connection Details (Azure Only)

1. Within the deployment.json, the azure_blob_storage_conn_str must be set.

2. The in-line comments outline the commands required to source this value from the Azure CLI.

5.3.1 Enabling Azure Key Vault Secrets

If you have the key_vault_secrets_provider_enabled=true value in the azure.json then the below secrets files would have been created during the execution of step 3.2:

You will need to add the following secrets to your azure key vault:

• worker-secret-appsettings-<cinchy_instance_name>

• web-secret-appsettings-<cinchy_instance_name>

• maintenance-cli-secret-appsettings-<cinchy_instance_name>

• idp-secret-appsettings-<cinchy_instance_name>

• forms-secret-config-<cinchy_instance_name>

• event-listener-secret-appsettings-<cinchy_instance_name>

• connections-secret-config-<cinchy_instance_name>

• connections-secret-appsettings-<cinchy_instance_name>

To create your new secrets:

1. Navigate to your key vault in the Azure portal.

2. Open your Key Vault Settings and select Secrets.

3. Select Generate/Import.

4. On the Create a Secret screen, choose the following values:

   1. Upload options: Manual.

   2. Name: Choose the secret name from the above list. They will all follow the format of: <app>-secret-appsettings-<cinchy_instance_name> or <app>-secret-config-<cinchy_instance_name>

   3. Value: The value for the secret will be the content of each app JSON located in the cinchy.kubernetes\environment_kustomizations\nonprod<cinchy_instance_name>\secrets folder, and as shown in above image.

   4. Content type: JSON

5. Leave the other values to their defaults.

6. Select Create.

Once you receive the message that the first secret has been successfully created, you may proceed to create the other secrets. There are a total of 8 secrets to create as shown in the above list of secret names.

5.4 Execute cinchy.devops.automations

This utility updates the configurations in the cinchy.terraform, cinchy.argocd, and cinchy.kubernetes repositories.

1. From a shell/terminal, navigate to the cinchy.devops.automations directory and execute the following command:

dotnet Cinchy.DevOps.Automations.dll "deployment.json"

2. If the file created in section 3 has a name other than "deployment.json", the reference in the command will will need to be replaced with the correct name of the file.

3. The console output should terminate with a "Completed successfully".

4. The updates must be committed to Git before proceeding to the next step.

6. Connect with kubectl

6.1 Update the Kubeconfig

6.1.1 AWS

1. From a shell/terminal run the following command, replacing <region> and <cluster_name> with the accurate values for those placeholders:

aws eks update-kubeconfig --region <region> --name <cluster_name>

6.1.2 Azure

1. From a shell/terminal run the following commands, replacing <subscription_id>, <deployment_resource_group>, and <cluster_name> with the accurate values for those placeholders.

az account set --subscription <subscription_id>
az aks get-credentials --admin --resource-group <deployment_resource_group> --name <cluster_name>

6.2 Verify the Connection

1. Verify that the connection has been established and the context is the correct cluster by running the following command:

kubectl config get-contexts

7. Deploy and Access ArgoCD

In this step, we will deploy and access ArgoCD.

7.1 Deploy ArgoCD

1. Launch a shell/terminal with the working directory set to the root of the cinchy.argocd repository.

2. Execute the following command to deploy ArgoCD:

bash deploy_argocd.sh

3. Monitor the pods within the argocd namespace by running the following command every 30 seconds until they all move into a healthy state:

kubectl get pods -n argocd

7.2 Access ArgoCD

1. Launch a new shell/terminal with the working directory set to the root of the cinchy.argocd repository.

2. Execute the following command to access ArgoCD:

bash access_argocd.sh

This script creates a port forward using kubectl to enable ArgoCD to be accessed at http://localhost:9090

The credentials for ArgoCD's portal are output at the start of the access_argocd's script execution in Base64. The Base64 value must be decoded to get the login credentials to use for the http://localhost:9090 endpoint.

8. Deploy Cluster Components

In this step, you will deploy your cluster components.

8.1 Deploy ArgoCD Applications

1. Launch a shell/terminal with the working directory set to the root of the cinchy.argocd repository.

2. Execute the following command to deploy the cluster components using ArgoCD:

bash deploy_cluster_components.sh

3. Navigate to ArgoCD at http://localhost:9090 and login. Wait until all components are healthy (this may take a few minutes).

8.2 Update the DNS

1. Execute the following command to get the External IP used by the istio ingress gateway.

kubectl get svc -n istio-system

2. DNS entries must be created using the External IP for any subdomains / primary domains that will be used, including Opensearch, Grafana, and ArgoCD.

8.3 Accessing Opensearch

The default path to access Opensearch, unless you have configured it otherwise in your deployment.json, is <baseurl>/dashboard

8.4 Accessing Grafana

The default path to access Grafana, unless you have configured it otherwise in your deployment.json, is <baseurl>/grafana

9. Deploy Cinchy Components

In this step, you will deploy your Cinchy components.

9.1 Deploy ArgoCD Application

1. Launch a shell/terminal with the working directory set to the root of the cinchy.argocd repository.

2. Execute the following command to deploy the Cinchy application components using ArgoCD:

bash deploy_cinchy_components.sh

3. Navigate to ArgoCD at http://localhost:9090 and login. Wait until all components are healthy (may take a few minutes)

4. You will be able to access ArgoCD through the URL that you configured in your deployment.json, as long as you created a DNS entry for it in step 8.2.

10. Troubleshooting

• If ArgoCD Application Sync is stuck waiting for PreSync jobs to complete, you can run the below command to restart the application controller.

kubectl rollout restart sts argocd-application-controller -n argocd

Table of Contents

1. General Kubernetes Deployment Prerequisites

The following is a list of steps that are required prior to deploying Cinchy v5 on Kubernetes.

1.1 Download your Tools

The following tools should be installed on the machine where the deployment will run:

• Terraform

• Kubectl (v1.23.0+)

• .NET Core 6.0.x

• Bash (Git Bash may be used on Windows)

1.2 Creating your Domains

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

• ArgoCD

• Opensearch

• Grafana

This is done through your specific domain registrar (for example: GoDaddy, Google Domains, etc.)

1.3 SSL Certs

You will need to have valid SSL Certs ready when you deploy Cinchy v5. This should be a wildcard certificate if ArgoCD will be exposed via a subdomain (preferred). Without the wildcard certificate, accessing ArgoCD's portal requires a port forward to be created using kubectl on demand.

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

1.4 Secrets Management

Secrets management is optional, however Cinchy recommends it for securely storing and accessing secrets that will be used in the deployment process. Cinchy currently supports:

• Amazon Secrets Manager

• Azure Key Vault

1.5 Single Sign-On

This is optional, but if you would like to set up single sign-on for use in your Cinchy v5 environments, please review the documentation here.

1.6 Docker Images

You have the option to either use Cinchy's Docker images or your own. If you would like to use Cinchy's, please follow the section below to access them.

1.6.1 Accessing Cinchy's Docker images

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

To gain access to Cinchy's Docker images, you will need login credentials to the ECR. You can gain these by contacting Cinchy Support.

1.7 Create your Repositories

The following four Git repositories must be created. Any source control platform supporting Git may be used, e.g. Gitlab, Azure DevOps, Github

• cinchy.terraform: This repo contains all Terraform configurations.

• cinchy.argocd: This repo contains all ArgoCD configurations.

• cinchy.kubernetes: This repo contains cluster and application component deployment manifests.

• cinchy.devops.automations: This repo contains the single configuration file and binary utility that maintains the contents of the above three repositories.

1.8 Access to Cinchy Artifacts

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

To access the Kubernetes artifacts:

1. Access the Cinchy Releases table. Please contact Cinchy Support if you do not 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.

2. Kubernetes Deployments (Azure Specific Requirements)

The following prerequisites are required if you are deployment Cinchy v5 on Azure.

• Terraform Backend 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.

• The Azure CLI should be installed on the machine where the deployment will be run. It must be set to the correct profile/login

• The deployment template has the option of either leveraging an existing resource group or creating a new one:

  • If an existing resource group is preferred, the prerequisite requires the following be provisioned in advance of the deployment:

    • The resource group.

    • A VNet within the resource group.

    • A single subnet. It's important that the address range be sufficient for all executing processes within the cluster, e.g. a CIDR ending with /22 to provide a range of 1024 IPs.

  • If a new resource group is preferred, all resources will be automatically provisioned.

• The quota limit of the Total Regional vCPUs and the Standard DSv3 Family vCPUs (or equivalent) must provide sufficient 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).

3. Kubernetes Deployments (AWS Specific Requirements)

The following prerequisites are required if you are deployment Cinchy v5 on AWS.

• Terraform Backend Requirements:

  • An S3 bucket that will contain the terraform state.

• The AWS CLI should be installed on the machine where the deployment will be run. It must be set to the correct profile/login

• The template has the option of either leveraging an existing VPC or creating a new one:

  • If an existing VPC is preferred, the prerequisite requires the following be provisioned in advance of the deployment:

    • The VPC. It's important that the address range be sufficient for all executing processes within the cluster, e.g. 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 sufficient for all executing processes within the cluster, e.g. 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.

  • If a new VPC is preferred, all resources will be automatically provisioned.

• The limit of the Running On-Demand All Standard vCPUs must provide sufficient 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).

• The SSL certificate must be imported into AWS Certificate Manager (or a new certificate can be requested via AWS Certificate Manager).

4. IIS Deployment Prerequisites

The following is a list of steps that are required prior to deploying Cinchy v5 on IIS

4.1 Access the Artifacts

You will need to access and download the Cinchy binary prior to deployment:

• Access the Cinchy Releases table. Please contact Cinchy Support if you do not have the access credentials necessary.

• Navigate to the release you wish to deploy

• Download the files listed under the Component Artifacts column. This should include zip files for:

  • Cinchy Platform

  • Cinchy Connections

  • Cinchy Event Listener

  • Cinchy Maintenance CLI and CLI (optional)

  • Cinchy Meta-Forms (optional)

4.2 General Requirements

1. An instance of SQL Server 2017+

2. A Windows Server 2012+ machine with IIS 7.5+ installed

3. Install .net core Hosting bundle Version 6.0

   • Specifically, install: ASP.NET Core/.NET Core Runtime & Hosting Bundle

4.3 System Requirements

Minimum Web Server Hardware Recommendations

• 2 x 2 GHz Processor

• 8 GB RAM

• 4 GB Hard Disk storage available

Minimum Database Server Hardware Recommendations

• 4 x 2 GHz Processor

• 12 GB RAM

• Hard disk storage dependent upon use case. Note that Cinchy maintains historical versions of data and performs soft deletes which will add to the overall storage requirements.

4.4 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 immediately be known to other nodes without establishing connectivity between them. For this reason the nodes must be able to communicate over either http or https through an IP based binding on the IIS server that allows cache expiration messages to be broadcast. The port used for this communication is different from the standard port that is 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.

4.5 Scaling Considerations

The web application is responsible for 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 fairly low as caching is limited to metadata, but the CPU utilization grows with request volume and complexity (e.g. insert / update operations are more complex than select operations). As the user population grows or request volume increases from batch processes / upstream system API calls 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 from batch processes / upstream system API calls the system may require additional CPU / Memory. Starting off in an environment that allows flexibility (e.g. a VM) would be advised until the real world load can be profiled and a configuration established. 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.

4.6 Backups

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

Certainly, presenting the information in a table can help make it easier to understand. Here's how you can structure it:

Before You Begin

Before starting with the ADFS configuration, make sure to have following information:

Having these details readily available will streamline the ADFS configuration process.

Configuration Steps in ADFS

1. Navigate to AD FS Management on your ADFS server.

2. Right-click on Relying Party Trusts and choose Add Relying Party Trust to open the Add Relying Party Trust Wizard.

3. In the wizard, select Claims Aware > Start > Select Data Source.

4. Select Enter Data About the Relying Part Manually > Next.

5. Fill in a Display Name under Specify Display Name.

6. Skip certificate configuration in Configure Certificates.

7. In Configure URL, select Enable support for the SAML 2.0 SSO Web SSO protocol.

8. Input your login URL as follows:

   Copy

   https://{your.cinchysso.url}/Saml2/Acs

9. Under Configure Identifiers, add an Identifier and press Next to complete the setup.

Set up Claim Issuance Policy

1. Right-click on the newly created Relying Party Trust (located by its Display Name) and select Edit Claim Issuance Policy.

2. Select Add Rule > Claim Rule > Send LDAP Attributes as Claims.

3. Input a Claim Rule Name.

4. In the Attribute Store, select Active Directory. Map the LDAP attributes to the corresponding outgoing claim types as shown in the table below:

1. Select Finish.

2. Select Edit Rule > View Rule Language. Copy the Claim URLs for later use in configuring your Cinchy appsettings.json. It should look like the following:

   Copy

   c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
     => issue(store = "Active Directory",
             types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
                       "sub",
                       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
                       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
                       "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
                       "http://schemas.microsoft.com/ws/2008/06/identity/claims/role"),
             query = ";userPrincipalName,sAMAccountName,givenName,sn,mail,memberOf;{0}",
             param = c.Value);

3. Press OK to confirm and save.

Configuration for Cinchy

Initial setup

1. Retrieve and save the Federation Metadata XML file from the following location: https://{your.ADFS.server}/FederationMetadata/2007-06/FederationMetadata.xml.

2. If needed, use IIS Manager to establish an HTTPS connection for the Cinchy website.

3. Also establish an HTTPS connection for the SSO site. Make sure the port number aligns with the one specified in the login URL.

Configuration for appsettings.json

App Settings Section

External identity claim section

You will need to refer to the Rule Language URLs you copied from the ADFS Configuration. Replace the placeholders below with your own URLs:

{
  "AppSettings": {
    // Replace placeholders below with URLS
  },
  "ExternalIdentityClaimSection": {
    "FirstName": {
      "ExternalClaimName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
    },
    "LastName": {
      "ExternalClaimName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
    },
    "Email": {
      "ExternalClaimName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
    },
    "MemberOf": {
      "ExternalClaimName": "http://schemas.microsoft.com/ws/2008/06/identity/claims/role"
    }
  }
}

Edit web.config

Insert the following lines within the <appSettings> section of your web.config file. Make sure to replace the {your.cinchy.url} and {your.cinchysso.url} with your Cinchy and Cinchy SSO values.

<appSettings>
  <!-- Replace placeholders below with URLS -->
  <add key="UseHttps" value="true" />
  <add key="StsAuthorityUri" value="https://{your.cinchy.url}" />
  <add key="StsRedirectUri" value="https://{your.cinchysso.url}/Account/LoginRedirect" />
  <!--  -->
</appSettings>

Table of Contents

1. Kubernetes vs IIS

When choosing to deploy Cinchy version 5, you must decide whether to deploy via Kubernetes or on a VM (IIS).

Kubernetes is an open-source system that manages and automates the full lifecycle of container-based applications. You now have the ability to deploy Cinchy v5 on Kubernetes, and with it comes a myriad of features that help to simplify your deployment and enhance your scaling. Kubernetes can maximize your container capacity and easily scale up/down with your current operations.

• Grafana, Opensearch, Opensearch Dashboard: Working together, these three applications provide a visual logging dashboard for all of the information coming in from your database pods. This streamlines your search for information by putting the control into your hands and compiling your logs in one easy to access place — you can now easily write a query against all of your logs, in all of your environments. You will have access to a default configuration out of the box, but you can also customize your dashboards as well.

• Prometheus: With the Kubernetes addition, you now have access to Prometheus for your metrics dashboard. Prometheus records real-time metrics in a time series database used for event monitoring and alerting. You can then create custom dashboards to display your data in an easy to use visual that makes reporting on your metrics easy, and even set up push alerts based on your custom needs.

You also have the option to run Cinchy on Microsoft IIS, which was the traditional deployment method prior to Cinchy v5. Internet Information Services (IIS) for Windows Server is a flexible, secure and manageable Web server for hosting anything on the Web.

We recommend using Kubernetes to deploy Cinchy v5, because of the robust features that you can leverage, such as improved logging and metrics. Using Kubernetes allows for a greater ability to scale your Cinchy instances as well as the ability to lower your costs by using PostgreSQL.

2. Choosing a Database

Before deploying Cinchy v5, you must select which database you want to use.

The following list outlines which databases we support for Kubernetes Deployments.

For IIS Deployments please review the architecture requirements here.

2.1 Microsoft SQL Server

2.1.1 MS SQL Server

• Microsoft SQL Server is a relational database management system. As a database server, it is a software product with the primary function of storing and retrieving data as requested by other software applications—which may run either on the same computer or on another computer across a network.

• Resource limits

2.1.2 Azure SQL Database

• Microsoft Azure SQL Database is a managed cloud database provided as part of Microsoft Azure. It runs on a cloud computing platform, and access to it is provided as a service. Managed database services take care of scalability, backup, and high availability of the database.

• Differences between Azure SQL and Azure Managed SQL

• Resource Limits

2.1.3 Azure Managed SQL Instance

• SQL Managed Instance is a managed, always up-to-date SQL instance in the cloud that combines broad SQL Server engine compatibility with the benefits of a fully managed PaaS.

• Differences between Azure SQL and Azure Managed SQL

• Resource Limits

2.2 Amazon Aurora

Amazon Aurora

• Amazon Aurora (Aurora) is a fully managed relational database engine that's compatible with MySQL and PostgreSQL. It combines the speed and reliability of high-end commercial databases with the simplicity and cost-effectiveness of open-source databases. Aurora is part of the managed database service Amazon Relational Database Service (Amazon RDS). Amazon RDS is a web service that makes it easier to set up, operate, and scale a relational database in the cloud.

• Resource Limits

2.3 PostgreSQL

2.3.1 PostgreSQL

• PostgreSQL is a free and open-source relational database management system emphasizing extensibility and SQL compliance. PostgreSQL comes with features aimed to help developers build applications, administrators to protect data integrity and build fault-tolerant environments, and help you manage your data no matter how big or small the dataset.

2.3.2 AWS RDS for PostgreSQL

• Amazon RDS makes it easy to set up, operate, and scale PostgreSQL deployments in the cloud. With Amazon RDS, you can deploy scalable PostgreSQL deployments with cost-efficient and resizable hardware capacity. Amazon RDS manages complex and time-consuming administrative tasks such as PostgreSQL software installation and upgrades; storage management; replication for high availability and read throughput; and backups for disaster recovery. Amazon RDS for PostgreSQL gives you access to the capabilities of the familiar PostgreSQL database engine.

• Resource Limits

2.3.3 Azure PostgreSQL Database

• This is a fully managed and intelligent Azure Database for PostgreSQL. Enjoy high availability with a service-level agreement (SLA) up to 99.99 percent, AI-powered performance optimization, and advanced security. A fully managed database that automates maintenance, patching, and updates. Provision in minutes and independently scale compute or storage in seconds.

• Resource Limits

3. Sizing Considerations and Requirements

Prior to deploying Cinchy version 5, you need to define your sizing requirements.

3.1 Sizing

3.1.1 Kubernetes Sizing

Cluster sizing recommendations vary and are dependant on a myriad of deployment factors. We have provided the following very general sizing recommendations, but encourage you to explore more personalized options.

CPU: 8 Cores

Memory: 32GB Ram

Number of Servers: 3

AWS: m5.2xlarge

Azure: D8 v3

3.1.2 IIS Sizing

For sizing recommendations and prerequisites concerning an IIS deployment, please review the documentation found here.

3.2 Application Storage Requirements

If you are choosing to deploy Cinchy v5 on IIS, then you need to ensure that your VM disks have enough application storage to run your clusters.

3.3 Object Storage Requirements

Cinchy supports both Amazon S3 and Azure Blob Storage.

If you are using Terraform for your Kubernetes deployment, you will need to set up a new S3 compatible bucket to manually to store your state file. You will also need a bucket for Connections, to store error files created during data syncs.

You will create your two S3 compatible buckets using either Amazon or Azure. Ensure that you use the following convention when naming your buckets so that the automation script runs correctly: <org>-<component>-<cluster>. These bucket names will be referenced in your configuration files when you deploy Cinchy on Kubernetes.

Example Terraform Bucket: cinchy-terraform-state

Example Connection Bucket: cinchy-connections-cinchy-nonprod

There is no sizing definitions, as S3 provides unlimited scalability and it charges only for what you use/how much you store on it.

• How to set up an Amazon S3 bucket

• How to set up Azure Blob Storage

1. Disabling your Applications

There may be times when you want to temporarily disable your Kubernetes pods in order to perform maintenance or certain upgrades. You can do so through the following steps:

1. Access your ArgoCD

2. Navigate to the application directory for the namespace you wish to disable, in this case development-cinchy (Image 1). You should see your cluster component applications.

3. Click on the main application (i.e. development-cinchy) (Image 2).

4. Navigate to Summary > Sync Policy > Automated. Click on Disable Auto-Sync > OK (Image 3).

5. For each of the cluster applications that you wish to disable, click on the "..." > Delete (Image 5).

6. Your apps should all appear as "out of sync" (Image 6).

2. Re-enabling your Applications

1. To re-enable your applications, return to the application directory for your disabled namespace (Image 7).

2. Click on the main application (i.e. development-cinchy) (Image 8).

3. Navigate to Summary > Sync Policy. Click on Enable Auto-Sync > OK (Image 9).

1. Overview

In Cinchy v5.2, we implemented the ability to free up database space by using S3 compatible or Azure Blob Storage for file storage. This configuration is set in the deployment.json of a Kubernetes installation, or the appsettings.json of an IIS installation.

2. Kubernetes File Storage

1. If you are using a Kubernetes deployment, you will change your file storage config in the deployment.json.

2. Navigate to the object storage section, where you will see either S3 or Azure Blob storage, depending on your deployment structure.

Azure Example

AWS Example

3. To utilize Blob Storage or S3, update each line with your own parameters.

4. To utilize Local storage, leave each line blank with the exception of the Connections_Storage_Type, which should be set to Local:

5. Run the deployment script by using the following command in the root directory of your devops.automations repo:

6. Commit and push your changes.

3. IIS File Storage

1. If you are using an IIS deployment, you will change your file storage config in the Cinchy Web appsettings file.

2. Locate the StorageType section of the file and set it to either "Local", "AzureBlobStorage" or "S3".

3. If you selected "AzureBlobStorage", fill out the following lines in the same file:

4. If your selected "S3", fill out the following lines in the same file:

1. Generate the self-signed certificate by executing the following commands in any folder:

2. Create a yaml file located at cinchy.kubernetes/platform_components/base/self-signed-ssl-root-ca.yaml.

3. Add the following to the yaml file:

4. Add the self signed root CA cert file to the cinchy.kubernetes/environment_kustomizations/cinchy_nonprod/base folder.

5. Add the yaml code snippet to the cinchy.kubernetes/environment_kustomizations/cinchy_nonprod/base/kustomization.yaml file, changing the below files key value as per your root ca cert file name:

6. Add the following line to the cinchy.kubernetes/platform_components/base/kustomization.yaml file

7. Add the below Deployment patchesJson6902 to each of your cinchy.kubernetes/environment_kustomizations/cinchy_nonprod/ENV_NAME/PLATFORM_COMPONENT_NAME/kustomization.yaml files, except "base".

• Ensure that the rootCA.crt file name is matched with ConfigMap data, configMapGenerator files, and the patch subpath.

8. Once the changes are deployed, verify the root CA cert is available on the pod under /etc/ssl/certs with below command, inputing your own POD_NAME and NAMESPACE where noted:

Table of Contents

Overview and Prerequisites

Cinchy version 5 on IIS comes bundled with common components such as Connections, Meta Forms, and the Event Listener. This page details the configuration and deployment instructions for the Cinchy Platform, including SSO. Click on the links below to be taken to the appropriate pages for other components:

Ensure that you review the prior to performing an IIS Deployment, including downloading all necessary artifacts from the

Please contact if you do not have the credentials required to access the artifacts table.

1. Create a Database

1. On your SQL Server 2017+ instance, create a new database named Cinchy (or any other name you prefer).

   1. If you choose an alternate name, in the remaining instructions wherever the database name is referenced, replace the word Cinchy with the name you chose.

2. A single user account with db_owner privileges is required for the Cinchy application to connect to the database. If you choose to use Windows Authentication instead of SQL Server Authentication, the account that is granted access must be the same account under which the IIS Application Pool runs.

2. Create an IIS Application Pool

1. On the Windows Server machine, launch an instance of PowerShell as Administrator.

2. Run the below commands to create the application pool and set its properties.

3. If you chose to use Windows Authentication in the database or want to run the application under a different user account, execute the below commands to change the application pool identity.

3. Create the Application Directories

2. Run the below commands in the Administrator instance of PowerShell to create directories for the application logs. Ensure your application pool account has write access to these directories.

4. Update the CinchySSO appsettings.json

1. Open the C:\CinchySSO\appsettings.json file in a text editor and update the values below.

4.1 App Settings

1. Under AppSettings section, update the values outlined in the table.

2. Wherever you see <base url> in the value, replace this with the actual protocol (i.e. http or https) and the domain name (or ip address) you plan to use.

Ex:. if you're using https with the domain app.cinchy.co, then <base url> should be replaced with https://app.cinchy.co

Below values are only required for SSO, otherwise leave them as blank

4.2 Connection String

In order for the application to connect to the database, the "SqlServer" value needs to be set.

1. Find and update the value under the "ConnectionStrings" section:

4.3 External Identity Claim Section

Under the "ExternalIdentityClaimSection" section you'll see the following values.

These values are used for SAML SSO. If you are not using SSO, keep these values as blank

4.4 Serilog

1. There is a "serilog" property that allows you to configure where it logs to. In the below code, update the following:

   1. "Name" must be set to "File" so it writes to a physical file on the disk.

   2. Set "path" to the file path to where you want it to log.

5. Update the Cinchy appsettings.json

1. Navigate to C:\Cinchy

2. Navigate to the appsettings.json file and update the following properties:

5.1 AppSettings

5.2 Connection String

In order for the application to connect to the database, the "SqlServer" value needs to be set.

1. Find and update the value under the "ConnectionStrings" section:

5.3 Serilog

1. There is a "serilog" property that allows you to configure where it logs to. In the below code, update the following:

   1. "Name" must be set to "File" so it writes to a physical file on the disk.

   2. Set "path" to the file path to where you want it to log.

6. Create the IIS Applications

1. Open an administrator instance of PowerShell

2. Execute the below commands to create the IIS applications and enable anonymous authentication. (This is required in order to allow authentication to be handled by the application)

7. Test the Application

1. Access the <base url>/Cinchy (e.g. http://app.cinchy.co/Cinchy) through Google Chrome.

2. Once the login screen appears, enter the credentials:

   1. The default username is admin and the password is cinchy.

   2. You will be prompted to change your password the first time you log in.

8. Next Steps

Navigate to the following sub-pages to deploy the following bundled v5 components: