Capability to edit existing environment properties¶

https://blueprints.launchpad.net/murano/+spec/environment-edit

The spec proposes mechanism for users to edit any details of an existing environment, for example edit its regions, set home region, change the networks or any other possible input field.

Problem description¶

Current Murano API and python-muranoclient only allow to specify its home region and default network during the environment creation. These parameters cannot be seen and cannot be updated by the user after the environment creation. Users may want to examine and change these or other environment properties after it is created. Adding a mechanism to apply custom JSON-patch to environment object model would provide this capability and add a great flexibility in managing environments.

Proposed change¶

Changes in API¶

It is proposed to create a new API endpoint /environments/<env_id>/model and two calls to it using GET and PATCH requests.

GET request provides environment object model where all environment properties can be seen. See the REST API impact section for the example of such output. If session is specified in the request and it is not in deploying state, response gives modified environment model from the session, otherwise actual environment model.

PATCH request allows to perform custom change to the environment object model using JSON-patch object. It requires session to be specified by request and saves changes to environment model in the specified session.

JSON-patch is a valid JSON that contains a list of changes to be applied to the current object. Each change contains a dictionary with three keys: op, path and value. op (operation) can be one of the three values: add, replace or remove`. See RFC 6902 [1] for details.

To indicate that body of the request is JSON-patch and validate correct format of the body, a new media type should be added - application/env-model-json-patch. During the validation in the middleware, the following conditions must be checked against the passed object:

It is a valid JSON-patch object (already implemented for application/murano-packages-json-patch media type and should be reused). Otherwise 400 Bad Request response is given.
Not all kinds of operations can be applied to all sections of the environment model. The list of allowed operations is the following:
- defaultNetworks: replace
- name: replace
- region: replace
- regions: add, replace, remove
- services: add, replace, remove
- ?: add, replace, remove
Attempt to perform the restricted change will result in the 403 Forbidden response.
Types of the environment properties and possible values are validated by the appropriate JSON-schema. Otherwise 400 Bad Request response is given.

Changes in python-muranoclient¶

To support the new API calls, corresponding python-muranoclient methods for environments are needed: get_model and update_model respectively.

New CLI command that displays the result of get_model method:

murano environment-model-show <ENV_ID> [--path <PATH>] [--session-id <SESSION_ID>]

<PATH> allows to get a specific section of the model, for example defaultNetworks, region or ? or any of the subsections. It defaults to ‘/’ which means getting the whole model. Specifying <SESSION_ID> allows to get the state of the environment with pending changes, while omitting it gives the actual state.

New CLI command that allows to update environment model with a custom patch:

murano environment-model-edit <ENV_ID> <FILE> --session-id <SESSION_ID>

The command calls update_model method with data (JSON-patch) provided in the <FILE> file. Changes are to be saved in session <SESSION_ID>.

Alternatives¶

Separate CLI command can be created for updating each environment property. It will be somewhat easier for users because file with JSON-patch will not be needed. On the other hand, it will require creating a bunch of commands instead of one generic and necessity to add new commands in future for the possible new properties.

Data model impact¶

None

REST API impact¶

Get environment model

Method	URI	Header	Description
GET	/environments/<env_id>/model/<path>	X-Configuration-Session (optional)	Get an Environment model

Specifying <path> allows to get a specific section of the model, for example defaultNetworks, region or ? or any of the subsections.

Response

Content-Type: application/json

{
    "defaultNetworks": {
        "environment": {
            "internalNetworkName": "net_two",
            "?": {
                "type": "io.murano.resources.ExistingNeutronNetwork",
                "id": "594e94fcfe4c48ef8f9b55edb3b9f177"
            }
        },
        "flat": null
    },
    "region": "RegionTwo",
    "name": "new_env",
    "regions": {
        "": {
            "defaultNetworks": {
                "environment": {
                    "autoUplink": true,
                    "name": "new_env-network",
                    "externalRouterId": null,
                    "dnsNameservers": [],
                    "autogenerateSubnet": true,
                    "subnetCidr": null,
                    "openstackId": null,
                    "?": {
                        "dependencies": {
                            "onDestruction": [{
                                "subscriber": "c80e33dd67a44f489b2f04818b72f404",
                                "handler": null
                            }]
                        },
                        "type": "io.murano.resources.NeutronNetwork/0.0.0@io.murano",
                        "id": "e145b50623c04a68956e3e656a0568d3",
                        "name": null
                    },
                    "regionName": "RegionOne"
                },
                "flat": null
            },
            "name": "RegionOne",
            "?": {
                "type": "io.murano.CloudRegion/0.0.0@io.murano",
                "id": "c80e33dd67a44f489b2f04818b72f404",
                "name": null
            }
        },
        "RegionOne": "c80e33dd67a44f489b2f04818b72f404",
        "RegionTwo": {
            "defaultNetworks": {
                "environment": {
                    "autoUplink": true,
                    "name": "new_env-network",
                    "externalRouterId": "e449bdd5-228c-4747-a925-18cda80fbd6b",
                    "dnsNameservers": ["8.8.8.8"],
                    "autogenerateSubnet": true,
                    "subnetCidr": "10.0.198.0/24",
                    "openstackId": "00a695c1-60ff-42ec-acb9-b916165413da",
                    "?": {
                        "dependencies": {
                            "onDestruction": [{
                                "subscriber": "f8cb28d147914850978edb35eca156e1",
                                "handler": null
                            }]
                        },
                        "type": "io.murano.resources.NeutronNetwork/0.0.0@io.murano",
                        "id": "72d2c13c600247c98e09e2e3c1cd9d70",
                        "name": null
                    },
                    "regionName": "RegionTwo"
                },
                "flat": null
            },
            "name": "RegionTwo",
            "?": {
                "type": "io.murano.CloudRegion/0.0.0@io.murano",
                "id": "f8cb28d147914850978edb35eca156e1",
                "name": null
            }
        }
    },
    services: []
    "?": {
        "type": "io.murano.Environment/0.0.0@io.murano",
        "_actions": {
            "f7f22c174070455c9cafc59391402bdc_deploy": {
                "enabled": true,
                "name": "deploy",
                "title": "deploy"
            }
        },
        "id": "f7f22c174070455c9cafc59391402bdc",
        "name": null
    }
}

Code	Description
200	Environment model received successfully
403	User is not authorized to access environment
404	Environment is not found or specified section of the model does not exist

Update environment model

Request

Method	URI	Header	Description
PATCH	/environments/<env_id>/model/	X-Configuration-Session	Update an Environment model

Content-Type application/env-model-json-patch
Example

[{
  "op": "replace",
  "path": "/defaultNetworks/flat",
  "value": true
}]

Response

Content-Type: application/json

See GET request response.

Code	Description
200	Environment is edited successfully
400	Body format is invalid
403	User is not authorized to access environment or specified operation is forbidden for the given property
404	Environment is not found or specified section of the model does not exist

Versioning impact¶

None

Other end user impact¶

Users will get new CLI commands to examine and edit environment object model.

Deployer impact¶

None

Developer impact¶

None

Murano-dashboard / Horizon impact¶

New python-muranoclient method can be used for providing environment edit capability from GUI, but this perspective is out of scope of this spec.

Implementation¶

Assignee(s)¶

Primary assignee:: vakovalchuk

Work Items¶

Implement new API call to get object model of environment
Implement new API calls to update the object model of environment
Implement new python-muranoclient methods to support new API calls
Add shell command that allows to display environment object model
Add shell command that allows to apply JSON-patch to the environment model
Add the same commands to the OpenStack client shell

Dependencies¶

None

Testing¶

API calls should be tested by unit tests and tempest tests
CLI commands should be tested by unit tests

Documentation Impact¶

API calls should be described in the Murano API specification
CLI commands should be described in the end user guide

References¶

[1] https://tools.ietf.org/html/rfc6902

Capability to edit existing environment properties¶

Problem description¶

Proposed change¶

Changes in API¶

Changes in python-muranoclient¶

Alternatives¶

Data model impact¶

REST API impact¶

Versioning impact¶

Other end user impact¶

Deployer impact¶

Developer impact¶

Murano-dashboard / Horizon impact¶

Implementation¶

Assignee(s)¶

Work Items¶

Dependencies¶

Testing¶

Documentation Impact¶

References¶

Murano Specs

Navigation

Related Topics