Skip to content

Latest commit

 

History

History
134 lines (105 loc) · 5.26 KB

README.adoc

File metadata and controls

134 lines (105 loc) · 5.26 KB
Raw

Standalone Configuration Tool Example

Introduction

This folder contains an example project for demonstrating the usage of the standalone configuration tool.

Gateway Project

The source .pol and .env archives are located in the src folder of the example project. The archives are protected by the passphrase changeme.

It is a simple API Gateway project providing an HTTPS endpoint /version which returns a JSON with the version of the project.

$ curl -ks https://localhost:8443/version
{
  "version": {
    "artifact": "undefined",
    "buildTime": "1970-01-01T00:00:00",
    "name": "",
    "description": ""
  }
}

The project contains environmentalized attributes. So the values of the artifact and buildTime properties can be configured. Also the port and the host of the HTTPS endpoint is environmentalized.

📎

For testing, you could deploy the .fed archive on a gateway. Remember to change the group passphrase with the managedomain tool.

Hands On

The goal of this demo is to configure the environmentalized fields for a staging environment. Also the server and CA certificates will be replaced by the certificates of the staging environment.

The passphrase for the configured .fed archive will be changed to changed.

To execute the demo just start the run.cmd. It will generate a configured gateway.fed archive in the directory of the run.cmd file.

If you deploy the configured archive to a gateway the API call looks similar to the following example.

📎
 For deployment, remember to set the group passphrase via managedomain. 
$ curl -ks https://localhost:18443/version (1)
{
  "version": {
    "artifact": "demo-1.0.0", (2)
    "buildTime": "2019-12-16T20:38:11.080000", (3)
    "name", Demo, (4)
    "description": "Service for demonstration of configuration tool." (5)
  }
}

  1. Server and port is set to localhost:18443

  2. Artifact is replaced.

  3. Build time is automatically generated.

  4. Name is set.

  5. Description is set.

📎

You can check the archives with PolicyStudio by creating a new project from the .pol/.env file or from the .fed file.

Remember to use the passphrase changeme for the .pol`and `.env archive and the passphrase changed for the generated .fed file.

How does it work?

We have a set of configuration files in the config folder:

  • gateway.config.json: used to configure the environmentalized fields.

  • gateway.certs.json: used to replace certificates identified by their alias.

  • gateway.props.json: used for properties not applicable in the configuration or certs file. This file may be generated during the build process with values from external resources (e.g. configuration DB or secured vault).

  • gateway.crypt.json: used for confidential properties. All values in this file are encrypted.

📎
 For a description of the configuration files please check the User Guide

To decrypt the confidential values there is a key.binary file. This a file containing any arbitrary bytes. If you edit this file with a text editor be aware of the encoding and the end of line sequence.

🔥
 Never store the key file in the source code repository. Here it’s only for demonstration.

In this example some environment variables (INFO_NAME and NEW_SERVER_PASSWORD) are set. Then the buildfed tool will be invoked with the following parameters:

  • -e src/gateway.env: specifies the path to the input .env archive

  • -p src/gateway.pol: specifies the path to the input .pol archive

  • -c config/gateway.config.json: specifies the path to the environmentalized fields configuration file

  • --cert=config/gateway.certs.json: specifies the path to the certificates configuration file

  • --prop=config/gateway.props.json: specifies the path to a properties file

  • --prop=config/passwords.props.json: specifies the path to a second properties file

  • --output-fed=gateway.fed: specifies the path for the configured .fed archive

  • --passphrase-in=changeme: passphrase for input archives (.pol and .env)

  • --passphrase-out=changed: passphrase for the generated .fed file

  • -D artifact:demo-1.0.0: specifies the value of property artifact via the command line instead of from the configuration files

  • -F info.descr:config/description.txt: specifies to set the value of property info.descr from the content of the config/description.txt file

  • --secrets-file=config/gateway.crypt.json: specifies the path to a properties file containing confidential values

  • --secrets-key=key.binary: specifies the path to the key file for decrypting the confidential values

The tool reads the source archives, configures the environmentalized fields, replaces the certificates and write the configured .fed file.

📎
 The value of the build time is sourced from an auto-generated, tool internal, property.

Known Limitations

  • The run.cmd script is available for Windows only.