Service Definition - csap-platform/csap-core GitHub Wiki

Related :     Application Editor     Application Model     Environment Definition    

Contents:

Overview

The CSAP Application Editor enables teams to quickly add, update, and delete all configurable attributes associated with a deployment of a service. Key concepts:

  • every service deployed has access to the Global Environment Variables
  • a service artifact can be deployed from source or binary
  • the same service artifact can be used multiples times in either the same or completely separate applications
    • each instance could have differing REST endpoint urls, different environment variables, difference performance limits, etc.

Service templates provide a fully extensible set of deployment targets. Out of the box - CSAP supports the following service profiles for a given template:

  • Kubernetes
  • Docker
  • OS
  • Java JEE - both SpringBoot and Tomcat
Typical workflow
  • a service definition is updated - usually only in the dev environment
  • definition changes are checked into git - and become active in the dev environment
  • definition changes are loaded into other environments
    • depending on the nature of the change - services may need to be restarted. eg. if parameters are changed
Service Customization

Service templates are shared across all environments and deployments. A template is instantiated (Service Instance) by assigning it to a service cluster. Service instances may be customized using:

  • Environment Variables: defined in the CSAP Environment Definitions - specifically the use of configuration maps
  • Environment Definition - including support for importing base environment(s)
  • Service Definition Files: named csap-service.yaml; each line is processed in order shown below. Note only the LAST existing item on each line will be used.
- $$service-resources/, $$service-resources/common/
- $$service-resources/base-environment/ 
- $$service-resources/$$csap-environment/
Service Editor

The CSAP Service editor enables rapid creation of service templates used for full environment management. Key items include:

Section/Tab Description
OS Process information Service profile (os, docker, ...), process mapping, environment variables, ...
Container image name, container constraints, ...
Packaging mapping of service assets on the filesystem (eg. log files, configuration files, etc)
Files any related content, eg. kubernetes specifications, property files, etc
Jobs ability to schedule commands to be run, folders to be cleaned up, adhoc commands to be run, etc
Source includes the ability to deploy from either source, or distribution repos (eg. maven, dockerhub)
Alerts set limits for resource consumption, and CSAP Health
Performance define custom collection via http or jmx
Environments Any value defined in the other tabs is considered the default for all environments. the environment tab enables per environment customizations
Json Editor edit directly of any of the above
Runtime Variables

The following sources are used to seed the OS environment variables. They can be used in service jobs, and are set when starting/stopping services. They are shown in order of precedence (the last line will overwrite the first).

Source Description
csap-environment.sh * $csapPlatformWorking="$CSAP_FOLDER/working" ; * $csapPackageFolder="$CSAP_FOLDER/packages" ; * $csapSavedFolder="$CSAP_FOLDER/saved" ; * $csapDefinitionFolder="$CSAP_FOLDER/definition" * $csapDefinitionResources="$csapDefinitionFolder/resources" * $csapDefinitionProjects="$csapDefinitionFolder/projects"
csap deployment & jobs $csapName, $csapWorkingDir, $csapPort, $csapServer, $csapLife....
CSAP Environment Definitions: global configuration map Global variables used in every service
Service Definition: selected configuration maps from the environment definition configuraiton maps A service may optionally select one or more specific maps to be included
Service Definition: environment variable A specific variable for only the selected service
Template Variables

A key feature of the service definition is the ability to define and use attribute references. The variables may also be used in kubernetes specifications (will be updated during deployment). There are two distinct classes:

  • template only variables provided by csap
  • user defined variables provided by application teams.
    • Recommended naming convention: $$some-hypenated-name.
    • template substitution occurs as is; same value will also be exported to the environments using _ ; eg. $$a-b-c will be exported into env as a_b_c

Note: variables may be combined. eg launch url is typically specified as http://$$service-fqdn-host:$$service-primary-port

CSAP Provided Template variables

Variable Description
  • $$csap-base
  • $$csap-working
  • $$csap-environment
  • $$csap-agent-url
 the csap installation folder typically /opt/csap/csap-platform. the csap package extraction folder, contains logs of non container services. shortcut for $csapFolder/working the active environment of the host shortcut to the csap-agent root url
  • $$service-name
  • $$service-working
  • $$service-resources
  • $$service-environment
  • $$service-host
  • $$service-fqdn-host
 primary service definition attributes. the SERVICE working folder, typicall $csapWorking/; used in service templates. the SERVICE resource folder; typically $csapFolder/definition/resources/
  • $$service-namespace
  • $$service-image
  • $$service-replica-count
 docker/kubernetes variables
  • $$service-primary-port
  • $$service-primary-port+1-6
  • $$service-parameters
  • $$service-ajp-port
  • $$service-jmx-port
  • $$service-context
 The assigned port for the service; optionally supports +1 to +6 for groupings
  • SEARCH_FOR_RESOURCE

used to locate kubernetes deployment files based on traversing $$service-resources. The LAST location found will be used

- $$service-resources/
- $$service-resources/common/
- $$service-resources/base-environment/  (the LAST item listed in imports)
- $$service-resources/$$csap-environment/
  • $$kubernetes-nodeport
 while it can be used anywhere - typically used for launch url in definition using the nodeport of the specified kubernetes service: 
url: "$$kubernetes-nodeport?serviceName=$$service-name&path=/"
  • $$kubernetes-ingress
 while it can be used anywhere - typically used for launch url in definition using the specified ingress 
url: "$$kubernetes-ingress?path=/$$service-name/app/kibana#/discover"
  • $$kubernetes-pod-ip
 while it can be used anywhere - typically used for performing http collections of performance data of a rest endpoint 
httpCollectionUrl: http://$$kubernetes-pod-ip:$$service-primary-port \
	/$$service-name/csap/metrics/micrometers
  • $$kubernetes-dashboard
  • $$kubernetes-config
 resolves to kubernetes endpoints. Note that pod-ip will only be resolvable on kubelet hosts
Application Variables

$$your-name:

Any variable starting with $$ added to either the service variables, or the CSAP Environment Definitions configuration maps may be used in service definitions the variable will ALSO be passed as an environment variable: eg. $$some-test will be set as some_test

Service Jobs

Service Jobs enable teams to associate services with domain specific maintenance activities. Jobs may be invoked on demand, or scheduled. Job types include:

  • scripts: optionally parameterized, scripts can be used to invoke clis, include docker, csap, kubectl, curl, etc.
  • logrotation: one or more policies to rotate logs, ref. https://linux.die.net/man/8/logrotate policys can be defined and will be checked hourly for invokation
  • diskCleanUp: one or more policies to remove files/folder
⚠️ **GitHub.com Fallback** ⚠️