Deploy an Example Application with a SmoothGlue Deployment
A SmoothGlue Deployment provides a simplified interface for deploying applications using ArgoCD within Kubernetes clusters. It abstracts away the complexity of creating individual Kubernetes resources by allowing users to define deployments through a single, declarative resource.
What a SmoothGlue Deployment Does
The SmoothGlue Deployment allows users to define application deployments that will:
- Create and configure a namespace for the application
- Create an Argo CD Project with appropriate permissions and restrictions
- Deploy Argo CD Applications using the provided source configurations
- Configure image pull secrets and git repository credentials (optional)
- Configure Istio sidecar injection (optional - default)
- Configure VirtualServices for Istio routing (optional)
Concepts
Argo CD Project
An Argo CD Project allows the operator to define security boundaries of what resources can be deployed as well as define who can access the Project resources via the Argo CD UI.
An Argo CD Project is defined as an AppProject when creating Projects declaratively.
Argo CD Application
An Argo CD Application is the set of Kubernetes manifests to deploy. Argo CD supports Helm charts, Kustomize manifests and OCI images. An Application also defines how to reconcile and sync resources if the actual state drifts as well as allows users to restart deployed resources via the Argo CD UI.
Viewing the Application within the Argo CD UI is a great way to debug issues, as it allows Operators to retrieve logs from workloads. Additionally, SmoothGlue enforces security policies on Application resources. Those policy violations are viewable within the Argo CD UI and allow Operators to coordinate with the Helm chart developers for remediation.
Istio Virtual Service
A simplistic explanation of a Virtual Service is that it allows operators to define how external traffic is routed to Kubernetes Services within a Kubernetes cluster. They can be very complex to shape traffic by rewriting request URLs before they reach the workload or distribute traffic across Kubernetes Services.
The examples below will show basic usage of a Virtual Service with the goal of associating an external host name with an internal Kubernetes Service.
Please refer to the official Istio documentation when configuring more complex configurations.
Prerequisites
Before starting, ensure you have:
- A Kubeconfig for a SmoothGlue Run
- A registry pull token for the container images being used (if authorization is required)
- A Git or registry pull token for the repository that holds the Helm chart to be deployed (if authorization is required)
- Keycloak groups to provide management access of the deployed resources via the Argo CD UI (this should be the groups for the app dev team that requested their application be deployed)
- The Kubernetes Service name for the application (if configuring external access)
SmoothGlue Deployment Simple Example
As a simple example, we are going to deploy the guestbook example application provided by Argo CD.
This application will not deploy successfully by default. SmoothGlue enforces several security policies on the cluster that this example chart does not meet. However, this will provide a good example of how the Argo CD UI will present these security violations.
The particular security violations for this application are due to missing securityContext configurations for the deployments as well as the disallowed source registry of these container images.
Before applying the example please update:
groupsto use a group associated to the app dev team's user accounts (these are viewable from the Argo CD UI via theUser Infotab on the left-hand side)virtualServicehoststo use the domain of your SmoothGlue Run environment
apiVersion: smoothglue.io/v1alpha1
kind: Deployment
metadata:
name: guestbook-deployment
namespace: structsure-system
spec:
parameters:
# Namespace where the application will be deployed
namespace: my-app-guestbook
# ArgoCD Project configuration
appProject:
name: guestbook # Name of the ArgoCD project
# This is where we define security boundaries for what can be deployed via the `applications` below
clusterResourceWhitelist: [] # List of cluster resources to whitelist
namespaceResourceWhitelist:
- group: '*'
kind: '*' # Allow all namespace resources
# SSO groups allowed access to manage the Application resources via Argo CD UI
groups:
# `readOnly` allows the associated users to view the application resources and sync the application
readOnly:
- /org-test/my-app
# `privileged` allows the associated users to do anything for the application
privileged:
- /org-test/_admins
# List of Applications to deploy
applications:
# name must be lowercase
- name: guestbook-frontend
# Please see upstream docs on all available options for `source` and `syncPolicy` https://argo-cd.readthedocs.io/en/stable/user-guide/application-specification/
source:
repoURL: https://github.com/argoproj/argocd-example-apps.git
targetRevision: HEAD
path: guestbook
syncPolicy:
automated:
prune: true
selfHeal: true
# Optional Istio Virtual Service Config. See upstream docs for all available options: https://istio.io/latest/docs/reference/config/networking/virtual-service/
virtualService:
hosts:
- guestbook.<DOMAIN> # Update based on the domain of your SmoothGlue Run
http:
- route:
- destination:
host: guestbook-ui # Kubernetes Service to expose
port:
number: 80 # Kubernetes Service port to expose
After applying the example SmoothGlue Deployment manifest to the cluster, there should be a new Application in Argo CD. Please verify your user can see the application in the Argo CD UI and review some of the violations this chart has.
SmoothGlue Deployment Private Registry / Private Git Example
The following example deploys an example NPM project from SmoothGlue Cloud. If you don't have access to https://code.build.smoothglue.io, feel free to substitute the example chart with your own chart.
For authentication tokens, it is preferred to create dedicated tokens for deploying the given application. GitLab supports creating group access tokens or project access tokens. These tokens should have the following permissions:
read_repository- only required for Helm charts / manifests stored in Gitread_registry- required for pulling application container images or OCI artifacts for Helm charts stored in the container registry
For this example, please create personal access token in https://code.build.smoothglue.io with the permissions above. We will use that token for this example.
To configure credentials to authenticate to private registries or private Git repositories, SmoothGlue will accept a reference to additional secrets that contain those connection details. The following are example secrets in the format that SmoothGlue expects:
---
apiVersion: v1
kind: Secret
metadata:
name: test-image-pull-creds
namespace: structsure-system
# stringData allows secrets to be applied without having to base64 encoding the data
stringData:
registry.build.smoothglue.io: user:password # This is the registry for code.build.smoothglue.io
# credentials for multiple registries can be configured
# registry.example.com: user:password
---
apiVersion: v1
kind: Secret
metadata:
name: test-registry-creds
namespace: structsure-system
# stringData allows secrets to be applied without having to base64 encoding the data
stringData:
username: myUser
password: myPassword
Please substitute your credentials into the the above manifests and apply them to the cluster. Take note of the Secret names as they will be used to in the SmoothGlue Deployment example below.
This example will show how to configure the SmoothGlue Deployment to use the above secrets for accessing a private container registry as well as a private repo.
Before applying the example please update:
groupsto use a group associated to your Keycloak user account (these are viewable from the Argo CD UI via theUser Infotab on the left-hand side)virtualServicehoststo use the domain of your SmoothGlue Run environment
apiVersion: smoothglue.io/v1alpha1
kind: Deployment
metadata:
name: private-repo-example-deployment
namespace: structsure-system
spec:
parameters:
# Namespace where the application will be deployed
namespace: my-app-npm
# Secret containing one or more registry credentials
# This secret will be made available in the Application namespace
# as the secret named `deployment-private-registry`
imagePullSecretRef:
name: test-image-pull-creds
namespace: structsure-system
# ArgoCD Project configuration
appProject:
name: private-repo-example # Name of the ArgoCD project
# This is where we define security boundaries for what can be deployed via the `applications` below
clusterResourceWhitelist: [] # List of cluster resources to whitelist
namespaceResourceWhitelist:
- group: '*'
kind: '*' # Allow all namespace resources
# SSO groups allowed access to manage the Application resources via Argo CD UI
groups:
# `readOnly` allows the associated users to view the application resources and sync the application
readOnly:
- /org-test/my-app
# `privileged` allows the associated users to do anything for the application
privileged:
- /org-test/_admins
applications:
# name must be lowercase
- name: private-repo-example-frontend
# Please see upstream docs on all available options for `source` and `syncPolicy` https://argo-cd.readthedocs.io/en/stable/user-guide/application-specification/
source:
# This Helm chart is stored as OCI image for this project. Note that we are using `chart` instead of `path` in this example
repoURL: registry.build.smoothglue.io/getting-started/examples/javascript-npm-example/helm
chart: javascript-npm-example
targetRevision: 0.1.0+80620
helm:
# values can also be supplied via a multi-line string
values: |
image:
tag: 80620
# SmoothGlue standardizes the image pull secret to `deployment-private-registry`
# The secret configured above will copied and be transformed into valid image pull secret format
imagePullSecrets:
- name: deployment-private-registry
# Disable some extra security / resource limits to make this chart more generically applicable to SmoothGlue Run clusters
securityContext:
appArmorProfile: null
limitRange:
enabled: false
resourceQuota:
enabled: false
# Adjust network policy to allow ingress from the SmoothGlue default gateway
networkPolicies:
istioNamespaceLabels:
app.kubernetes.io/name: istio-gateway
# Configure source manifest repo credentials
secretRef:
name: test-registry-creds
syncPolicy:
automated:
prune: true
selfHeal: true
# Optional Istio Virtual Service Config. See upstream docs for all available options: https://istio.io/latest/docs/reference/config/networking/virtual-service/
virtualService:
hosts:
- private-repo-example.<DOMAIN> # Update based on the domain of your SmoothGlue Run
http:
- route:
- destination:
host: private-repo-example-frontend-javascript-npm-example
port:
number: 8080
After applying the example SmoothGlue Deployment manifest to the cluster, there should be a new Application in Argo CD. Please verify your user can see the application in the Argo CD UI. Additionally, you should be able to access the application using the hostname configured under virtualService.
Architecture
The following diagram depicts how a SmoothGlue Deployment works:
