Overview

This section will guide you through the considerations and the prerequisites 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 Cinchy recommends a Kubernetes deployment. It also walks you through selecting a database to run your deployment on and 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 about 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.

Deployment planning checklist

Use the following checklist when planning for your Cinchy v5 deployment. Each item links to the appropriate documentation page.

• Will you run on Kubernetes or a VM?

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

• Kubernetes offers the ability to elastically scale.

• IIS limits certain components to running single instances.

• As all caching is in memory in an IIS deployment, if multiple instances are online for redundancy there is point to point communication between them (HTTP requests on the server IPs) required to maintain the cache.

• Performance is better on Kubernetes because of Kafka/Redis

• Prometheus/Grafana and OpenSearch aren't available in an IIS deployment

• The Maintenance CLI runs as a CronJob in Kubernetes while this needs to be orchestrated using a scheduler for an IIS deployment.

• Upgrades are simpler with the container images on Kubernetes.

Kubernetes checklist

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 repository (GitHub or similar).

IIS checklist

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.

Component diagram

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

Component overview

Infrastructure configuration (on cluster)

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

AWS infrastructure configuration (outside cluster)

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

Infrastructure component overview

Azure infrastructure configuration (outside cluster)

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

Infrastructure component overview

Cluster level component overview

The following highlighted area provides a high-level overview of cluster level components used when deploying Cinchy on Kubernetes and what versions they're 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.

• Service Mesh - Istio: Istio handles and routes all inbound traffic to your Cinchy instance, keeping it secure and managed.

• Monitoring/Alerting - Prometheus & Grafana: Prometheus consumes metrics from the running components in your environment, which you can visualize into user friendly graphs and dashboards by Grafana. Prometheus can also connect to third party services to provide alerting capabilities. Both Prometheus and Grafana use persistent storage.

• Logging - OpenSearch and Fluent Bit: OpenSearch captures and indexes all logs in a single, accessible location. These logs can be queried, searched, and filtered, and Correlation IDs mean that they can also be traced across various components. These logging components take advantage of persistent storage.

• Caching - Redis: Redis facilitates a distributed lock using RedLock, which guarantees lock synchronizations across Cinchy instances. It's also a storage location for the execution output when running batch data syncs.

• Event Processing - Kafka: This acts as the middleware for messaging between components through a queuing mechanism. Kafka features persistent storage.

Cluster configuration

Before you deploy Cinchy on Kubernetes, consider the following about 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?

Instance component overview

Each Cinchy instance uses the following components to either provide an experience to users/applications or connect data in/out of Cinchy. You can deploy multiple Cinchy instances per cluster, so 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).

• Meta Experiences: Cinchy offers pre-packaged experiences that you can import into your Cinchy environment and use on your data network. This includes experiences like Meta-Forms and Meta-Reports.

• Connections: Use the Cinchy Connections experience to create data syncs in/out of the platform. It features persistent storage.

• Data Browser: Cinchy’s data collaboration 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. Cinchy uses IdPs authentication services to authenticate end-users.

• Event Listener: The Event Listener picks up events from connected sources during a data sync. Review the Data Sync page for further information on the Event Listener. The Event Listener uses persistent storage.

• Event Stream Worker: The Event Stream Worker processes data picked up by the Event Listener during data syncs. Review the Data Sync page for further information on the Event Stream Worker. The Event Worker uses persistent storage.

• Maintenance (Batch Jobs): Cinchy performs maintenance tasks through the CLI. This includes the data erasure and data compression deletions.

GitOps

ArgoCD is a declarative, GitOps continuous delivery tool for Kubernetes that simplifies the application deployment and lifecycle management. ArgoCD is highly recommended for deploying Cinchy, but you can also use another tool.

Once you set up the configurations, 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).

Introduction

This section guides 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 the Cinchy Support team:

• Via email: support@cinchy.com

• Via phone: 1-888-792-6051

• Through the support portal:

Kubernetes vs IIS

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

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, which helps to simplify your deployment and enhance your scaling. Kubernetes can maximize your container capacity and scale up/down with your current operations.

• Grafana, OpenSearch, OpenSearch Dashboard: Working together, these three applications provide a visual logging dashboard for all 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 write a query against all your logs, in all 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 , which was the traditional deployment method before Cinchy v5. Internet Information Services (IIS) for Windows Server is a flexible, secure and manageable Web server for hosting anything on the Web.

Choose a database

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

The following list outlines the supported databases for Kubernetes Deployments.

For IIS Deployments

Microsoft SQL Server

• Microsoft SQL Server is a relational database management system. As a database server, it's 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.

• 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's provided as a service. Managed database services take care of scalability, backup, and high availability of the database.

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

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 cloud web service that makes it easier to set up, operate, and scale a relational database.

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.

• Amazon RDS makes it easy to set up, operate, and scale cloud-based PostgreSQL deployments. 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.

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

Sizing considerations and requirements

Before deploying Cinchy v5, you need to define your sizing requirements.

Sizing

Kubernetes sizing

Cluster sizing recommendations vary and are dependant on a number of deployment factors. We've provided the following 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

IIS sizing

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.

Object storage requirements

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.

Example Terraform Bucket: cinchy-terraform-state

Example Connection Bucket: cinchy-connections-cinchy-nonprod

S3 provides unlimited scalability and it charges only for what you use/how much you store on it, so there are no sizing definitions.

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:

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:
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:

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.

Group management

This section defines how to manage Groups.

Cinchy Groups

Cinchy Groups are containers that have Users and other Groups within them as members. Use Groups 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, only members of the Cinchy Administrators group can manage this table Each group has the following attributes:

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.

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.

Group membership sync

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's 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.

Dependencies

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

3. You must have a task scheduler to perform the sync on a regular basis (For example, AutoSys).

Configuration steps

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 and name assigned to the query will be referenced in the next step.

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. Create an entry with the config in your Data Sync Configurations table (part of the Cinchy CLI model).

Sync execution & scheduling

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.

Parameters

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:

Update the server max Request Header size

CinchySSO AppSettings

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

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:

• Terraform

• Kubectl (v1.23.0+)

• .NET Core 6.0.x

• Bash (You can also use Git Bash on Windows)

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:

• Amazon Secrets Manager

• Azure Key Vault

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 the section below 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.

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.

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

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:

• The resource group.

• A VNet within the resource group.

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

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).

• 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:

• Access the Cinchy Releases table. Please contact Cinchy Support if you don't 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)

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

System requirements

Minimum web server hardware recommendations

• 2 × 2 GHz Processor

• 8 GB RAM

• 4 GB Hard Disk storage available

Minimum database server hardware recommendations

• 4 × 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 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 Cconsiderations

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.

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

2. Find the following line:

add key="TlsVersion" value=""

1. Replace the above line with the following:

add key="TlsVersion" value="1.2"

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

2. Find the following line:

add key="TlsVersion" value=""

1. Replace the above line with the following:

add key="TlsVersion" value="1.2" 

1. Restart the application pools in IIS for the changes to take effect.

Overview

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

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

        "object_storage": {
          // Cinchy requires a new Azure Blob Storage container for it's file storage. Select a unique name, the template convention follows cinchy
          // Storage Account Names can only consist of lowercase letters and numbers, and must be between 3 and 24 characters long
          "storage_account_name": "cinchynonprod",
          // Two storage containers are created, one for the Connections component and one for the Platform. The default naming convention is -
          "connections_storage_container_name": "nonprod-connections",
          "platform_storage_container_name": "nonprod-platform",
          "connections_storage_type": "AzureBlobStorage",
          // The connection string to the Azure Blob Storage account, it can be retrieved by executing the following command after the terraform apply has completed
          // In the below command the  and  must be replaced with the values for those properties within this file
          // az storage account show-connection-string --name  --resource-group 
          "azure_blob_storage_conn_str": ""
        },

AWS Example

        "object_storage": {
          // Cinchy requires a new S3 bucket for it's file storage. Select a unique name, the template convention follows -
          "cinchy_s3_bucket": "-cinchy-nonprod",
          // During the S3 bucket creation, a tag named "Environment" is added to the resource and populated with the following value
          "cinchy_s3_environment_tag": "cinchy-nonprod",
          "connections_storage_type": "S3",
          // IAM user credentials (access key and secret) for access to this bucket. Ensure that the usre has the necessary privileges defined in IAM
          "connections_s3_access_key": "",
          "connections_s3_secret_access_key": "",
          // Optional - only set this value if you are using a third party S3 compatible service
          "connections_s3_service_url": ""
        },

1. To use Blob Storage or S3, update each line with your own parameters.

2. To use Local storage, leave each line blank except for the Connections_Storage_Type, which you should set to Local:

          "connections_storage_type": "Local",

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

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

1. Commit and push your changes.

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.

  "AppSettings": {
   ...
    "StorageType": ""      // Set this to "Local" to store files within Cinchy's database. Set this to "AzureBlobStorage" to store files within Azure Blob Storage. Set this to "S3" to store files within S3.
  },

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

  "AzureBlobStorageSettings": {
    "ConnectionString": "",    // ConnectionString used to connected to the Azure Blob Storage
    "Container": "",       // The container for Cinchy's file storage
    "BasePath": ""         // The base directory path of where to store files within the container (eg. cinchy/files)
  },

1. If you selected S3, fill out the following lines in the same file:

  "S3Settings": {
    "AccessKey": "",       // Access Key for the IAM user. Ensure that the user has the necessary privileges defined in IAM
    "SecretAccessKey": "", // Secret for the IAM user. Ensure that the user has the necessary privileges defined in IAM
    "Region": "",          // Region of where the S3 bucket is located in
    "Bucket": "",          // S3 bucket for Cinchy's file storage
    "BasePath": "",            // The base directory path of where to store files within the bucket (eg. cinchy/files)
    "ServiceURL": ""       // (Optional) - only set this value if you are using a third party S3 compatible service
  }

Overview

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.

Prerequisites

System Requirements

• SQL SERVER 2017+

• SSMS (optional)

• Install IIS 7.5+ / enable IIS from Windows features

• Dotnet 6

DotNet 6 Installation

• DotNet Core 6 SDK which includes ASP.NET Core /.NET Core Runtime

• DotNet Core 6 Hosting Bundle

Minimum Hardware Requirements

• 2 × 2 GHz Processor

• 8 GB RAM

• 4 GB Hard Disk storage available

Minimum Database Server Hardware Recommendations

• 4 × 2 GHz Processor

• 12 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.

Get Access to Cinchy.net (Cinchy Prod Access)

• Access to Cinchy.net (Cinchy Prod) can be obtained during onboarding.

• Alternatively, users can request access by sending an email to support@cinchy.com.

Access Cinchy Releases Table from Cinchy UI

Navigate to the Cinchy Releases table from the Cinchy user interface.

Download Release Artifacts

Download the following items from the "Release Artifacts" column:

• Cinchy VX.X.zip

• Cinchy Connection

• Cinchy Event Listener

• Cinchy Meta-Forms (optional)

• Cinchy Maintenance CLI (optional)

Create a Database

1. On your SQL Server 2017+ instance, create a new database and name it Cinchy.

1. Create a single user account with db_owner privileges for Cinchy to connect to the database. If you choose to use Windows Authentication instead of SQL Server Authentication, the authorized account must be the same account that runs the IIS Application Pool.

Create an IIS application pool

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

2. Copy and run the PowerShell snippet below to create the application pool and set its priorities. You can also manually create the app pool via the IIS Manager.

3. Verify Db_name → Security → Users → select the user → properties → membership

Import-Module WebAdministration
$applicationPoolNameSSO="CinchySSO"
$applicationPoolNameWeb="CinchyWeb"
New-WebAppPool -Name $applicationPoolNameSSO
$appPath = "IIS:\AppPools\"+ $applicationPoolNameSSO
$appPool = Get-IISAppPool $applicationPoolNameSSO
$appPool.managedRuntimeVersion = ""
Set-ItemProperty -Path $appPath -Name managedRuntimeVersion $appPool.managedRuntimeVersion
Set-ItemProperty "IIS:\AppPools\$applicationPoolNameSSO" -Name Recycling.periodicRestart.time -Value 0.00:00:00
Set-ItemProperty "IIS:\AppPools\$applicationPoolNameSSO" -Name ProcessModel.idleTimeout -Value 1.05:00:00
Set-ItemProperty "IIS:\AppPools\$applicationPoolNameSSO" -Name Recycling.periodicRestart.privateMemory -Value 0
New-WebAppPool -Name $applicationPoolNameWeb
Set-ItemProperty "IIS:\AppPools\$applicationPoolNameWeb" -Name Recycling.periodicRestart.time -Value 0.00:00:00
Set-ItemProperty "IIS:\AppPools\$applicationPoolNameWeb" -Name ProcessModel.idleTimeout -Value 1.05:00:00
Set-ItemProperty "IIS:\AppPools\$applicationPoolNameWeb" -Name Recycling.periodicRestart.privateMemory -Value 0

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

$credentials = (Get-Credential -Message "Please enter the Login credentials including your Domain Name").GetNetworkCredential()
$userName = $credentials.Domain + '\' + $credentials.UserName
Set-ItemProperty "IIS:\AppPools\$applicationPoolNameWeb" -name processModel.identityType -Value SpecificUser
Set-ItemProperty "IIS:\AppPools\$applicationPoolNameWeb" -name processModel.userName -Value $username
Set-ItemProperty "IIS:\AppPools\$applicationPoolNameWeb" -name processModel.password -Value $credentials.Password
Set-ItemProperty "IIS:\AppPools\$applicationPoolNameSSO" -name processModel.identityType -Value SpecificUser
Set-ItemProperty "IIS:\AppPools\$applicationPoolNameSSO" -name processModel.userName -Value $username

Create the application directories

1. Download and unzip the "Cinchy vX.X" application package from the Releases Table. This will create two directories: Cinchy and CinchySSO. For example, if you unzip at the root of your C drive, the two directories will be C:\Cinchy and C:\CinchySSO.

2. Make sure your application pool accounts has read and execute access to these directories.

4. Run the below commands in the Administrator instance of PowerShell to create separate directories for Errorlogs and Logs.

md C:\CinchyLogs\Cinchy
md C:\CinchyLogs\CinchySSO
md C:\CinchyErrors

Update the CinchySSO appsettings.json

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

App Settings

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

SSO installation

For more information on the SSO installation, please seee the SSO installation page

Connection string

To connect the application to the database, you must set the SqlServer value.

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

   Copy

   "SqlServer" : ""

SQL Server Authentication example

"SqlServer" : "Server=MyServer;Database=Cinchy;User ID=cinchy;Password=password;Trusted_Connection=False;Connection Timeout=30;Min Pool Size=10;TrustServerCertificate=True;"

SQL Server Windows Authentication example

"SqlServer" : "Server=MyServer;Database=Cinchy;Trusted_Connection=True;Connection Timeout=30;Min Pool Size=10;"

Serilog

Cinchy has a serilog property that configures where the logs are located. In the below code, update the following:

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

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

• Replace "WriteTo" section with following:

"WriteTo": [
      {
        "Name": "File",
        "Args": {
// For the "path" variable, please refer to the original path in your system where these log folders were created.
          "path": "C:\\CinchyLogs\\CinchySSO\\log.json",
          "preserveLogFilename": true,
          "shared": "true",
          "rollingInterval": "Day",
          "rollOnFileSizeLimit": true,
          "fileSizeLimitBytes": 100000000,
          "retainedFileCountLimit": 30,
          "formatter": "Serilog.Formatting.Compact.CompactJsonFormatter, Serilog.Formatting.Compact"
        }
      }
    ]

Update appsettings.json

1. Navigate to the installation folder for Cinchy (C:\Cinchy).

2. Open the appsettings.json file and update the following properties:

AppSettings

Setup the connection string

To connect the application to the database, the SqlServer value needs to be set.

SQL Server Authentication example

"SqlServer" : "Server=MyServer;Database=Cinchy;User ID=cinchy;Password=password;Trusted_Connection=False;Connection Timeout=30;Min Pool Size=10;TrustServerCertificate=True;"

SQL Server Windows Authentication example

"SqlServer" : "Server=MyServer;Database=Cinchy;Trusted_Connection=True;Connection Timeout=30;Min Pool Size=10;"

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 to allow authentication to be handled by the application).

New-WebApplication -Name Cinchy -Site 'Default Web Site' -PhysicalPath C:\Cinchy -ApplicationPool CinchyWeb
New-WebApplication -Name CinchySSO -Site 'Default Web Site' -PhysicalPath C:\CinchySSO -ApplicationPool CinchySSO
Set-WebConfigurationProperty -Filter "/system.webServer/security/authentication/anonymousAuthentication" -Name Enabled -Value True -PSPath IIS:\ -Location "Default Web Site"

Test the application

1. Access the <base url>/Cinchy (http://app.cinchy.co/Cinchy) through a web browser.

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

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

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

Next steps

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

• Connections Deployment

• Event Listener/Worker Deployment

• Maintenance CLI

1. Execute the following commands in any folder to generate the self-signed certificate:

openssl genrsa -des3 -out rootCA.key 4096

openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.crt

openssl genrsa -out mydomain.com.key 2048

openssl req -new -sha256 -key mydomain.com.key -subj "/C=US/ST=CA/O=MyOrg, Inc./CN=mydomain.com " -out mydomain.com.csr

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

2. Add the following to the YAML file:

apiVersion: v1
kind: ConfigMap
metadata:
  name: self-signed-ca-pemstore
data:
  rootCA.crt: |
    <rootCA.crt>

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

2. 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:

configMapGenerator:
- name: self-signed-ca-pemstore
  behavior: replace
  files:
  - rootCA.crt

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

- self-signed-ssl-root-ca.yaml

1. 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.

    - op: add
      path: /spec/template/spec/volumes/-
      value: 
        configMap:
          name: self-signed-ca-pemstore
        name: self-signed-ca-pemstore  
    - op: add
      path: /spec/template/spec/containers/0/volumeMounts/-
      value: 
        mountPath: /etc/ssl/certs/rootCA.crt
        name: self-signed-ca-pemstore
        subPath: rootCA.crt

1. Once the changes are deployed, verify the root CA cert is available on the pod under /etc/ssl/certs with below command. Make sure to input your own POD_NAME and NAMESPACE:

 kubectl exec -it POD_NAME -n NAMESPACE -- openssl x509 -in /etc/ssl/certs/rootCA.crt -text

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.

Deployment prerequisites

To install Cinchy v5 on Kubernetes, you need to follow the requirements below. Some requirements depend on whether you deploy on Azure or on AWS.

All platforms

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

• You must create the following four Git repositories. You can use any source control platform that supports Git, such as GitLab, Azure DevOps, and 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.

• 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 repositories created above.

• Install the following tools on the deployment machine:

  • Terraform

    • For an introduction to Terraform + AWS, see this Get started Guide.

    • For an introduction to Terraform + Azure, see this Get started Guide

  • kubectl (v1.23.0+)

  • .NET Core 6 required for Cinchy v5.8 and higher.

  • Bash (Git Bash may be used on Windows)

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

• You will need a single domain for accessing ArgoCD, Grafana, OpenSearch Dashboard, and any deployed Cinchy instances. You have 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.

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

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:

• The resource group.

• A virtual network (VNet) within the resource group.

• A single subnet. It's important that the range be enough for all executing processes within the cluster, such as a CIDR ending with /22 to provide a range of 1024 addresses.

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 range be enough for all executing processes within the cluster, such as a CIDR ending with /21 to provide a range of 2048 IP addresses.

  • 3 Subnets (one per AZ). It's important that the range be enough for all executing processes within the cluster, such as a CIDR ending with /23 to provide a range of 512 IP addresses.

  • 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).

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

Initial configuration

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

Configure the deployment.json file

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

2. Depending on 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.

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"

1. 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.

2. The console output should have the following message:

Completed successfully

Terraform deployment

The following steps detail how to deploy Terraform.

Cinchy.terraform repository structure - AWS

If deploying on AWS: Within the Terraform > AWS directory, a new folder named eks_cluster is created. Nested within that's 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 repository structure - Azure

If deploying on Azure: Within the Terraform > Azure directory, a new folder named aks_cluster is created. Nested within that's 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.

Cloud provider authentication

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

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

1. For Azure, run the following command and follow the on screen instructions to authenticate the session:

az login

Deploy the infrastructure

1. Execute the following command to create the cluster:

bash create.sh

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

The resource creation process can take about 15 to 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 repository.

Retrieve the SSH keys

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

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

Azure SSH keys

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

Update the deployment.json

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

Update the database connection string

1. Navigate to 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 has 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.

Create the IAM user for S3 (AWS)

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

Update blob storage connection details (Azure)

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.

Enable 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. You must create a total of 8 secrets, as shown in the above list of secret names.

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"

1. 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.

2. The console output should end with the following message:

Completed successfully

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

Connect with kubectl

Update the Kubeconfig

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>

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>

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

Deploy and access ArgoCD

In this step, you will deploy and access ArgoCD.

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

1. 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

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 script execution in Base64. The Base64 value must be decoded to get the login credentials to use for the http://localhost:9090 endpoint.

Deploy cluster components

In this step, you will deploy your cluster components.

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

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

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

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

Access OpenSearch

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

Access Grafana

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

Deploy Cinchy components

In this step, you will deploy your Cinchy components.

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

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

2. 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.

## 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

Overview

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.

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 the next section.

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

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 IDE (Visual Studio, VsCode), 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 IDE (Visual Studio, VsCode), 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 correctly configured by verifying the output 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

Authorize 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"
    }
  ]
}

Confirmation

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

1. Navigate to the cinchy.kubernetes repository > 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:

Overview

Cinchy supports integration with any Identity Provider that issues SAML tokens (such as 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).

Configure SAML authentication - IIS deployments

You must register Cinchy 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 of Cinchy is the base URL of the CinchySSO application followed by "{AcsURLModule}/Acs"

https:///\<CinchySSO URL>/Saml2/Acs

https://myCinchyServer/Saml2/Acs

To enable SAML authentication within Cinchy, do the following:

1. You can find the necessary metadata XML from the applicable identity provider. Place the metadata file in the deployment directory of the CinchySSO web application.

1. 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 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 you enable SSO, the next time a user arrives at the Cinchy login screen they will see an additional button for Single Sign-On".

Configure SAML authentication - Kubernetes deployments

1. Retrieve your metadata.xml file from your identity provider.

1. Navigate to your cinchy.kubernetes\environment\_kustomizations\_template\instance\_template\idp\kustomization.yaml file.

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

- target:
    version: v1
    kind: Secret
    name: idp-secret-appsettings
  patch: |-
    - op: replace
      path: /data/appsettings.json
      value: <<idp_appsettings_json>>
    - op: add
      path: /data/metadata.xml
      value: <<metadata.xml>>

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

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

"sso": {
    "SAMLClientEntityId": "cinchy-dev", // Cinchy instance name
    "SAMLMetadataXmlPath": "/usr/share/appsettings/metadata.xml",
    // All below values get from metadata.xml and fill them here.
    "SAMLIDPEntityId": "",
    "SAMLSSOServiceURL": "",
    "AcsURLModule": "",
    "FirstNameExternalClaimName": "",
    "LastNameExternalClaimName": "",
    "EmailExternalClaimName": "",
    "MemberOfExternalClaimName": "",
    "metadata.xml": "BASE64_ENCODED_METADATA.XML"
}

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

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

{
    "ConfigSettings": {
        "AppSettings": {
            "SAMLClientEntityId": "<<SAMLClientEntityId>>",
            "SAMLIDPEntityId": "<<SAMLIDPEntityId>>",
            "SAMLMetadataXmlPath": "<<SAMLMetadataXmlPath>>",
            "SAMLSSOServiceURL": "<<SAMLSSOServiceURL>>",
            "AcsURLModule": "<<AcsURLModule>>",
        },
        "ExternalIdentityClaimSection": {
            "FirstName": {
                "ExternalClaimName": "<<FirstNameExternalClaimName>>"
            },
            "LastName": {
                "ExternalClaimName": "<<LastNameExternalClaimName>>"
            },
            "Email": {
                "ExternalClaimName": "<<EmailExternalClaimName>>"
            },
            "MemberOf": {
                "ExternalClaimName": "<<MemberOfExternalClaimName>>"
            }
        }
    }
}

1. Run DevOps automation script which will populate the updated outputs into the cinchy.kubernetes repository.

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

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

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

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.

Define a new SSO User

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

Convert an existing user to SSO User

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

Login with SSO

When a user is configured for SSO, they can select Login with Single Sign-On on the login page, which directs logins through the Identity Provider's authentication flow.