Team development with YAML configuration
3 minute read
You can convert common and API projects, created using Policy Studio Team development functionality, into YAML configurations in the same way as any other XML federated configuration. The converted YAML projects will validate successfully, but may need the
--allow-invalid-ref option to pass validation as some of these projects might contain entities that reference entities in another project.
progupgrade tools cannot be used with the YAML entity store. The equivalent of
projpack can be done using the
yamles import command. There is no support or need yet for the upgrade of YAML configurations.
You can use the
projdeploy tool with YAML configuration, but the input into this is a YAML
.tar.gz file built using standard tooling. The design of the YAML configuration lends itself well to Team development for many use cases. The natural split of the configuration into separate files allows multiple developers to make changes on the same YAML configuration project without causing merge conflicts. The conflicts that do occur, are more easily understood and resolved as files are smaller and more human readable.
It is still necessary to support multiple YAML configuration projects for reuse purposes. Developers might want to develop policies once and reuse many times in other projects. For example, a company might have some common security or throttling policies that they wish to apply across all projects. Such policies can be developed once and imported into other projects at deployment time through a CI/CD pipeline. You can import many common projects into your main project before deployment by using the
yamles import command multiple times.
The following example shows how a merged
.tar.gz file can be created for deployment from two separate projects. Let’s assume our starting point is a pair of projects that were created in XML format in Policy Studio using the Team Development templates, one using the
Common Project and the other using the
common-security project created using the
Common Project template contains a
Common security policy as follows:
test-apiproject, created using the API Project template contains a simple policy named
Test, with a
- A listener on port
/testis linked to this policy.
common-securityproject is added as a Team development project dependency via File > Manage Dependencies.
Common securitypolicy is selected as a
Global Request Policy(Right-click the policy as selecting Set as Global Request Policy).
Both projects can be converted separately to YAML using the
yamles fed2yaml option.
./yamles fed2yaml --source federated:file:/home/user/apiprojects/common-security/configs.xml -o ~/team-dev/common-security --targz ~/team-dev/archives/common-security.tar.gz ./yamles fed2yaml --source federated:file:/home/user/apiprojects/test-api/configs.xml -o ~/team-dev/test-api --targz ~/team-dev/archives/test-api.tar.gz
They may be separately validated as follows:
./yamles validate --source yaml:file:/home/user/team-dev/common-security ./yamles validate --source yaml:file:/home/user/team-dev/test-api --allow-invalid-ref
Note the use of
--allow-invalid-ref for the
test-api project as it has a reference to an entity in the
common-security project in the
System/Global Properties.yaml file:
--- type: GlobalProperties fields: name: Global Properties children: - type: ReferenceProperty fields: name: system.policy.request value: /Policies/Common security
/Policies/Common security.yaml file exists in the
CI/CD pipelines for the
test-api projects might each publish a
.tar.gz into Artifactory. These need to get merged before deployment using the
yamles import command.
./yamles import --source ~/team-dev/archives/common-security.tar.gz --target ~/team-dev/archives/test-api.tar.gz
test-api.tar.gz will contain the policies from the
common-security projects. The
test-api.tar.gz should validate without the
./yamles validate --targz ~/team-dev/archives/test-api.tar.gz
test-api.tar.gz can be deployed in the usual way via
Currently, the import command does not support project dependencies in the same way as XML. You must ensure the final project has all references resolved. This can be verified using the
yamles validate command. The ordering and use of
addOrReplace in [
_fragment.yaml files](/docs/apim_yamles/apim_yamles_cli/yamles_cli_importexport/#how-the-_fragment.yaml-file-is-used-for-export] will determine how to resolve conflicts.
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.