This article is designed to help guide you through implementing Replicated features into your application and more broadly into your organization. This includes recommendations for integration into your continuous integration environments, deployment manifests, and Vendor Portal and even further into things like how best to integrate your support process with ours and how to use the cloud native functionality that using Replicated brings to help you sell your own software.
As you go through this architecture we will include design decisions that were used to help you understand why a particular decision was made. You can use this knowledge to also help you understand when your particular situation means a different decision is advantageous. This architecture is meant to give you a path to success and not constrain your available options.
Architecture Overview
The way you build, release, and deploy your software is important to the success of running your commercial application in a customer-provided cloud-native environment. In this section, we explore the various components and decisions to best support deploying into those customer provided environments. We will cover the components of this architecture in more detail in the sections below.
Application Architecture
Your software architecture is an important consideration as part of making your application ready to run in customer provided environments. In general, following the design considerations outlined in the 12 Factor App will help you build applications that are resilient to failure and scale well in any cloud-native environment, on-prem or otherwise.
Consider the following design decisions when building your application:
Decision ID
Design Decision
Justification
Implication
APP-001
Avoid using cloud-proprietary services
Cloud proprietary services can lock your customers into a specific cloud and limit your future options
Increased cloud independence and lower support burden
APP-002
Use horizontally scalable services
Horizontally scalable services allow customers to scale as necessary to support increased demand
May limit some of your service options
APP-003
Use declaratively database schemas (see schemahero.io)
Allows seamless life cycle management of your application
None
APP-004
Wait for resources to become available
Avoids exposing crashloop backoff conditions to end users
provides expected end user behavior, same outcome can be achieved in packaging with init containers if necessary
Build Architecture
The most frequent intersection between Replicated and your own organization will be through the build process. We recommend that for every commit that passes your code quality checks, that you update container images you and promote the release to your unstable release channel. We also recommend signing your commits and container images to help validate the security of your supply chain.
Decision ID
Design Decision
Justification
Implication
BUILD-001
Integrate the Replicated cli with your CI workflow
Integration with your CI pipeline ensures that every iteration of your software is available for testing and can be promoted quickly to customers
None
BUILD-002
Use the --auto flag on the replicated release create command
This flag embeds best practices for creating replicated releases
The functionality of the auto flag may change as new best practices are implemented and release notes should be watched for change in behavior
BUILD-003
Sign all commits
Signing commits helps show you are conforming to a secure supply chain
None
BUILD-004
Sign container images and provide verification mechanism
Signing container images helps show you are conforming to a secure supply chain
None
Package Architecture
Packaging your application is a core part of its delivery to customers. We recommend that you simplify your packaging by following some standards such as aligning the branch name of your package repository to the branch names of your release channel. Additionally, we recommend that you package your application as a helm chart so that you can allow customers the flexibility of installing via helm directly or via the application console.
When packaging your software we recommend you follow the design considerations below:
Decision ID
Design Decision
Justification
Implication
PACK-001
Use a git branch per channel for your deployment repository that match the release channel in the vendor portal
This idiom lets you quickly identify which section of your source aligns to what release channel. It also follows the in-built --auto flags of the replicated CLI
None
PACK-002
Have preflight checks for any underlying constraints you have on the underlying kubernetes cluster
Preflight checks can guarantee your underlying platform meets your expectations
Missing preflight checks can result in later support calls when the application does not perform as expected
PACK-003
Use Helm charts to create your application manifests
Helm charts open up additional deployment options and allow you to build on other charts
While Helm charts open additional deployment options, they introduce additional complexity. Caution should be taken to keep the go templates as simple as possible. Additionally, manifests that are go templates are not parseable yaml which can limit options for linting and other automated manifest manipulation.
PACK-004
Do not package an ingress controller
Ingress should be provided by the distribution
Not providing an ingress controller means you must limit some of the ingress features you can use. A preflight check can be used to verify a compatible controller is being used.
Release Architecture
When a revision of your software has been tested and is ready to be released, we recommend that you use the package repository to communicate the changes they can expect in a release.
When releasing your software we recommend you follow the design considerations below:
Decision ID
Design Decision
Justification
Implication
RELE-001
For customer facing channels use semantic versioning
Semver will allow your customers to understand the expected impact of upgrading
Using semver requires diligences to maintain the expected contract with your customers
RELE-002
Match release channels and package repository branch names
Simplifies logic between systems
None
RELE-003
Be consistent in your versioning across channels
Consistent versioning will help if you want to switch a customer between channels
None
Customer Delivery Architecture
Customer Delivery is the final customer initiated action that will result in your application being installed into their environment. For first time deployments, We recommend that you provide a clear and concise installation guide that will help your customers get started with your application. We also recommend that you provide a clear and concise upgrade guide that will help your customers upgrade to new versions of your application. You can use our documentation templates mentioned in the documentation architecture section to help you get started.
For customer deployments we recommend you follow the design considerations below:
Decision ID
Design Decision
Justification
Implication
DELV-001
For each customer, guide them to use whichever cluster deployment model (existing vs embedded) they are already the most familiar or comfortable with.
All clusters can be run well, but not all customers can run all clusters. By meeting your customers where they are, you optimize their chance of success.
Replicated enables you to deploy anywhere, the most important thing to consider is what is best for that customer.
DELV-002
Enterprise customer should integrate with existing observability and logging platforms
Integrating with their existing stacks means the customer will be able to effectively manage the availability and performance of the installation
Providing procedures and documentation to help customers integrate with their existing log and monitoring platforms will help keep your software available and reduce MTTR when there is an issue.
Support Architecture
By integrating the replicated platform into your support processes you can gain significant improvements by reducing total cases and time to resolution. To best leverage these features be sure to integrate the support bundles and support bundle analyzers into your support or incident process.
Decision ID
Design Decision
Justification
Implication
SUPP-001
Integrate support bundles with your incident process
Support bundles help support teams rapid pinpoint the cause of incidents
Reduced time to resolve
SUPP-002
After each incident write an analyzer that would detect the issue in the future
Analyzers help the customer to self troubleshoot and remediate and increase confidence in the product
Less support cases & faster resolution of those opened
SUPP-003
At your initial deployment, add support analyzers for your known log files and issues
Analyzers help the customer to self troubleshoot and remediate and increase confidence in the product
Less support cases & faster resolution of those opened
SUPP-004
Create status informers for all your long running statefulsets and deployments
Status informers will allow the admin console to accurately depict the status of your application
Less support cases & accurate representation of state and telemetry
Documentation Architecture
Documentation is an important part of all software. By using replicated, you can integrate our documentation into your existing documentation framework.
Decision ID
Design Decision
Justification
Implication
DOCS-001
Integrate the Enterprise section of docs into your own documentation
Replicated provided documentation reduces burden on your technical writing staff
None
DOCS-002
Watch the replicated-docs repository for changes and update your docs accordingly
Up to date docs help you and your customers install and support efficiently
Up to date docs help you and your customers install and support efficiently
None
Sales Architecture
By using Replicated, you gain access to a host of features for your application that help you sell more and run proof-of-concepts (POCs) better.
Decision ID
Design Decision
Justification
Implication
SELL-001
Integrate replicated sales collateral into your own
Replicated collateral helps articulate the value the Replicated platform brings to your customers
Enhanced sales
SELL-002
Integrate replicated license management with your SFDC (Salesforce Datacenter)
This gives you a single source of truth in the existing system you have
Customer clarity and simplified operations
Worksheet
This model has a worksheet with each of the decisions in a tabular format. You can copy this worksheet and for each decision here track if you are following the model or provide architectural notes on why a different decision was reached.
