Build Configuration

go-msx Build uses YAML build configuration files to define the build to be executed. A build configuration describes the build metadata for one of:

• Microservice
• Command Line tool
• Service Pack
• Library

A build configuration file can include these artifacts:

• Binary artifacts
• Assemblies (tarballs)
• Resources
• Runtime Configuration Files
• Docker Images

Configuration Sources

Like all go-msx applications, go-msx-build can retrieve configuration from a variety of sources:

• Environment
• Command-Line Options
• Build Configuration Files
• Application Configuration Files
• Defaults

To specify the primary build configuration file, pass the --config option to build:

go run cmd/build/build.go --config cmd/build/build.yml

This will normally be handled by the Makefile.

Configuration passed in by either Environment Variables or Command-Line Options will override values also specified in Files or Defaults.

Environment Variables

Some settings are intended to be injected from environment variables. These include:

• docker.username (DOCKER_USERNAME)
• docker.password (DOCKER_PASSWORD)
• artifactory.username (ARTIFACTORY_USERNAME)
• artifactory.password (ARTIFACTORY_PASSWORD)
• build.number (BUILD_NUMBER)
• manifest.folder (MANIFEST_FOLDER)
• jenkins.username (JENKINS_USERNAME)
• jenkins.password (JENKINS_PASSWORD)
• github.token (GITHUB_TOKEN)

It is considered unsafe or inflexible to store them directly in the configuration file. The default generated Jenkinsfile will automatically inject these environment variables as required by the relevant steps.

Application Configuration

Some settings below are intended to be read from the application configuration files.
These include:

• info.app.* - bootstrap.yml
• server.* - bootstrap.yml

To ensure these are being read from the correct source, ensure the executable.config-files list contains the base application configuration files (eg bootstrap.yml).

Example:

executable:
  configFiles:
    - bootstrap.yml

Configuration Sections

executable

The executable configuration specifies the entrypoint and primary configuration file(s) of this build.

Example:

executable:
  configFiles:
    - bootstrap.yml
    - dnaservice.production.yml

msx

The msx configuration specifies details of the MSX release to interface with.

Example:

msx:
  release: 3.10.0
  deploymentGroup: dna
  platform:
    parentArtifacts:
      - com.cisco.vms:vms-service-starter
      - com.cisco.vms:vms-service-starter-core
      - com.cisco.vms:vms-service-starter-kafka
      - com.cisco.nfv:nfv-integration-consul-leader
    version: 3.10.0-EDGE
    includeGroups: "com.cisco.**"

docker

The docker configuration controls interactions with the docker daemon, global repository, images, and Dockerfile scripts.

Example:

docker:
    dockerfile: build/package/Dockerfile

kubernetes

The kubernetes configuration provides defaults for generating kubernetes manifests.

manifest

The manifest configuration specifies how to build and publish installer manifests.

resources

The resources section identifies the files to be included as part of the docker image.

Each entry has the following properties:

Example:

resources:
  includes:
    - "/internal/migrate/**/*.sql"
    - "/internal/populate/**/*"
  excludes:
    - "/internal/populate/**/*.go"

assemblies

The assemblies configuration specifies .tar file generation. The .tar files will be included in generated manifests and published (unless disabled).

Example:

assemblies:
  root: platform-common

assemblies.custom

The assemblies.custom setting contains a list of custom assemblies to generate. These will be uploaded to artifactory and recorded as binaries in the manifest, unless disabled with artifactory.assemblies.

Each entry in this list has the following properties:

Example:

To create an assembly file called "skyfallui-files-${release}-${build}.tar":

assemblies:
  custom:
    - path: ui/build
      pathPrefix: services
      manifestPrefix: skyfallui-files
      manifestKey: ${msx.deploymentGroup}-ui

• Each file from the ui/build subtree will be prefixed with the services folder in the output tar. e.g. 'ui/build/dna/index.js' will be relocated to services/dna/index.js.
• The assembly will be added to the generated artifact manifests at e.g. dna-ui.

artifactory

The artifactory configuration specifies artifactory connectivity, folders, binaries, and images.

Example:

artifactory:
  installer: deployments/production
  images:
    - nacservice

artifactory.custom

The artifactory.custom setting contains a list of custom binaries to include. These will be uploaded to artifactory and recorded in the manifest.

Each entry in this list has the following properties:

Example:

artifactory:
  custom:
    - path: deploymentvariables/nac_deployment_variables.yml
      outputName: nac_deployment_variables.yml
      manifestPrefix: deployment-variables
      manifestKey: deployment_variables
    - path: deploymentvariables/nac_variables.yml
      outputName: nac_variables.yml
      manifestPrefix: variables
      manifestKey: variables    

generate

The generate configuration specifies paths to be generated by the generate target. Mostly these will refer to folders on which to run go generate to produce mocks.
Specialized generators such as openapi are described in following sections.

NOTE: Embedding using vfs has been deprecated in favor of go:embed which executes during the go build process.

generate[*].openapi

The openapi generator can be used to auto-generate OpenApi clients from contract specifications.

go

The go configuration specifies environment variables and options to be passed to Go tools during the build.

build

The build configuration specifies information about the build used to generate buildinfo.yml.

info.app

The info.app configuration specifies details about the application used across all parts of the build.

Example:

info.app:
    name: dnaservice
    attributes:
      displayName: DNA Microservice

server

The server configuration specifies details about the web server used across all parts of the build.

Example:

server:
    port: 9393

jenkins

The jenkins configuration specifies details about the Jenkins CI server used by the project.

Example:

jenkins.job: eng-sp-umbrella/builds/umbrellaservice

github

The github configuration specifies details about the GitHub Source Control server used by the project.

Example:

github.organization: xiaoydu

aws

The aws configuration specifies credentials and target details for AWS.

These values default to the standard environment variables (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY) so no extra configuration should be required if using them.

deploy

The deploy configuration specifies the target for package deployment.

openapi

The openapi configuration specifies producer and consumer contract locations (local and upstream), along with schema resolution aliases.

Example:

# Contract Management
openapi:
  # Local (producer) API contract
  spec: api/openapi.yaml

  # Remote (consumer) API contract pairs
  contracts:
    - consumer: internal/stream/.openapi/manage-service-8.yaml
      producer: https://cto-github.cisco.com/raw/NFV-BU/msx-platform-specs/develop/manage-service-8.yaml

  # Alternative sources for well-known schema
  alias:
    - from: https://api.swaggerhub.com/domains/Cisco-Systems46/msx-common-domain/8
      to: https://cto-github.cisco.com/raw/NFV-BU/msx-platform-specs/sdk1.0.10/common-domain-8.yaml