Skip to content

Improve upgrade doc #112

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
PavitraS wants to merge 24 commits into
base: main
Choose a base branch
from
Draft

Improve upgrade doc #112

Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
826992a
NPT-644 Add support to upgrade nexus DM using compiler
Nov 21, 2022
3415482
Fix pkg import
Nov 30, 2022
a54ae25
Fix makefile
Nov 30, 2022
8a67e72
Fix review remarks
Dec 7, 2022
5176e5c
Fix tests
pavithra-kavach Dec 17, 2022
377795f
make file changes
pavithra-kavach Dec 19, 2022
e72c21f
Handle empty crds file
pavithra-kavach Dec 19, 2022
62ca8b9
Merge branch 'main' into npt-644-upgrade
pavithra-kavach Jan 3, 2023
afa82a2
Ignore go mod errors
pavithra-kavach Jan 11, 2023
3406034
Update go.mod with common-library
pavithra-kavach Jan 11, 2023
90e6183
change permisssions to _generated folder
janakiramanmesh7 Jan 13, 2023
d97dba7
change permission for build directory instead of _generated
janakiramanmesh7 Jan 16, 2023
76bf80e
Generate code
pavithra-kavach Jan 16, 2023
93fa0c4
Merge branch 'main' into npt-644-upgrade
PavitraS Jan 17, 2023
cb19d24
Modify log to print full file path
pavithra-kavach Jan 17, 2023
c8c6d01
Address review remarks
pavithra-kavach Jan 18, 2023
9c3a039
Update tests
pavithra-kavach Jan 18, 2023
dc26434
Revert "change permisssions to _generated folder"
pavithra-kavach Jan 19, 2023
3e9d893
Improve upgrade doc
pavithra-kavach Jan 20, 2023
f28b492
Improve doc
pavithra-kavach Jan 23, 2023
650e206
Improve table
pavithra-kavach Jan 23, 2023
86a971b
Merge branch 'main' into dm-upgrade-doc
PavitraS Jan 23, 2023
63844b9
Explain the rules in detail
pavithra-kavach Jan 24, 2023
c10d670
Improve doc
pavithra-kavach Jan 24, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
278 changes: 278 additions & 0 deletions docs/getting_started/UpgradingDatamodel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,278 @@
# Upgrading the Datamodel

## Purpose

The purpose of Datamodel Upgrade is to make it possible to reinstall Datamodel without having to first uninstall and then reinstall it.

## Parameters

### Common parameters(Build + Install)


| Name | Description | Type | Shorthand | Value |
|---------|------------------------------|:----:|:---------:|:--------|
| `force` | Force upgrade of a datamodel | bool | f | `false` |


### Build parameters

| Name | Description | Type | Value |
|--------------------|-------------------------------------------------------|:------:|:----------------------|
| `prev-spec-dir` | The path to the directory containing all current CRDs | string | `build/crds` |
| `prev-spec-branch` | Branch of current CRDs to compare to new CRDs | string | `current branch HEAD` |

* if "prev-spec-dir" is provided, (users can provide a directory path), where all the CRD's can be found. We would use those files as a source of truth.
* if "prev-spec-branch" is given, we can use the specified branch to figure out the CRDs directory. Otherwise, default to the HEAD of the current working branch.

Specify each parameter using the `--key=value` argument to `nexus datamodel build`. For example,

```
$ nexus datamodel build --name orgchart --force=false --prev-spec-dir=<build/crds> --prev-spec-branch=<master>
```

The above command builds the new datamodel against the master branch of the build/crds directory.

## What is considered a non-breaking change?

##### 1. Add an optional field in the nexus node (field with "omitempty" tag )

<details>
<summary>Show example</summary>

1. Add an optional field called `Location` (field with `omitempty` tag) in the node
```
type Leader struct {
// Tags "Root" as a node in datamodel graph
nexus.Node

Name string
Designation string
DirectReports Manager `nexus:"children"`
+ Location string `json:"location,omitempty"`
}

2. Rebuild your datamodel
```
nexus datamodel build --name orgchart
```

Now, the build would succeed

</details>

##### 2. Modify the REST APIs URIs

<details>
<summary>Show example</summary>

1. Remove the GET URI from the spec
```shell
var LeaderRestAPISpec = nexus.RestAPISpec{
Uris: []nexus.RestURIs{
- {
- Uri: "/leader/{root.Leader}",
- Methods: nexus.DefaultHTTPMethodsResponses,
- },
{
Uri: "/leaders",
Methods: nexus.HTTPListResponse,
},
},
}

// nexus-rest-api-gen:LeaderRestAPISpec
type Leader struct {
nexus.Node Name string
Designation string
DirectReports Manager `nexus:"children"`
Location string `json:"location,omitempty"`
}

2. Rebuild your datamodel
```
nexus datamodel build --name orgchart
```

Now, the build would succeed

</details>

##### 3. Modify the REST APIs annotation

<details>
<summary>Show example</summary>

1. Modify the `nexus-rest-api-gen` annotation spec from `LeaderRestAPISpec` to `NewLeaderRestAPISpec`

```shell
var NewLeaderRestAPISpec = nexus.RestAPISpec{
Uris: []nexus.RestURIs{
{
Uri: "/leaders",
Methods: nexus.HTTPListResponse,
},
},
}

// nexus-rest-api-gen:NewLeaderRestAPISpec <==
type Leader struct {
nexus.Node Name string
Designation string
DirectReports Manager `nexus:"children"`
Location string `json:"location,omitempty"`
}

2. Rebuild your datamodel
```
nexus datamodel build --name orgchart
```

Now, the build would succeed

</details>

## What is considered a backward incompatible change?

##### 1. Add a required field in the nexus node

<details>
<summary>Show example</summary>

1. Add a required field called `AdditionalField` in the existing nexus node
```
type Leader struct {
// Tags "Root" as a node in datamodel graph
nexus.Node

Name string
Designation int
DirectReports Manager `nexus:"children"`
Location string `json:"location,omitempty"`
+ AdditionalField string
}

2. Rebuild the datamodel
```
nexus datamodel build --name orgchart
```

Now, the build would fail and display the incompatible changes as shown below.
```
panic: Error occurred when checking datamodel compatibility: datamodel upgrade failed due to incompatible datamodel changes: \n"
time="2023-01-24T12:21:56+05:30" level=error msg="\t > detected changes in model stored in leaders.root.orgchart.org\n"
time="2023-01-24T12:21:56+05:30" level=error msg="\t > \n"
time="2023-01-24T12:21:56+05:30" level=error msg="\t > spec changes: \n"
time="2023-01-24T12:21:56+05:30" level=error msg="\t > /spec/versions/name=v1/schema/openAPIV3Schema/properties/spec/required\n"
time="2023-01-24T12:21:56+05:30" level=error msg="\t > + one required field added:\n"
time="2023-01-24T12:21:56+05:30" level=error msg="\t > - additionalField\n"
time="2023-01-24T12:21:56+05:30" level=error msg="\t > \n"
time="2023-01-24T12:21:56+05:30" level=error msg="\t > \n"
time="2023-01-24T12:21:56+05:30" level=error msg="\t > \n"
time="2023-01-24T12:21:56+05:30" level=error msg="\t > \n"
time="2023-01-24T12:21:56+05:30" level=error msg="\t > \n"

3. Use the `—force=true` flag to ignore any build failures and obtain successful code generation.
```
nexus datamodel build --name orgchart --force=true
```

</details>

##### 2. Remove a required field from the nexus node

<details>
<summary>Show example</summary>

1. Remove a required field called `AdditionalField` from the `Leader` node
```
type Leader struct {
// Tags "Root" as a node in datamodel graph
nexus.Node

Name string
Designation int
DirectReports Manager `nexus:"children"`
Location string `json:"location,omitempty"`
- AdditionalField string
}

2. Rebuild the datamodel
```
nexus datamodel build --name orgchart
```

Now, the build would fail and display the incompatible changes as shown below.

```
panic: Error occurred when checking datamodel compatibility: datamodel upgrade failed due to incompatible datamodel changes: \n"
time="2023-01-24T14:08:00+05:30" level=error msg="\t > detected changes in model stored in leaders.root.orgchart.org\n"
time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n"
time="2023-01-24T14:08:00+05:30" level=error msg="\t > spec changes: \n"
time="2023-01-24T14:08:00+05:30" level=error msg="\t > /spec/versions/name=v1/schema/openAPIV3Schema/properties/spec/properties\n"
time="2023-01-24T14:08:00+05:30" level=error msg="\t > - one field removed:\n"
time="2023-01-24T14:08:00+05:30" level=error msg="\t > additionalField:\n"
time="2023-01-24T14:08:00+05:30" level=error msg="\t > type: string\n"
time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n"
time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n"
time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n"
time="2023-01-24T14:08:00+05:30" level=error msg="\t > /spec/versions/name=v1/schema/openAPIV3Schema/properties/spec/required\n"
time="2023-01-24T14:08:00+05:30" level=error msg="\t > - one required field removed:\n"
time="2023-01-24T14:08:00+05:30" level=error msg="\t > - additionalField\n"
time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n"
time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n"
time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n"
time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n"
time="2023-01-24T14:08:00+05:30" level=error msg="\t > \n"

3. Use the `—force=true` flag to ignore any build failures and obtain successful code generation.
```
nexus datamodel build --name orgchart --force=true
```

</details>

##### 3. Remove an optional field from the nexus node (field with "omitempty" tag )

<details>
<summary>Show example</summary>

1. Remove an optional field called `Location` from the `Leader` node
```
type Leader struct {
// Tags "Root" as a node in datamodel graph
nexus.Node

Name string
Designation int
DirectReports Manager `nexus:"children"`
- Location string `json:"location,omitempty"`
}

2. Rebuild the datamodel
```
nexus datamodel build --name orgchart
```

Now, the build would fail and display the incompatible changes as shown below.

```
panic: Error occurred when checking datamodel compatibility: datamodel upgrade failed due to incompatible datamodel changes: \n"
time="2023-01-24T20:56:26+05:30" level=error msg="\t > detected changes in model stored in leaders.root.orgchart.org\n"
time="2023-01-24T20:56:26+05:30" level=error msg="\t > \n"
time="2023-01-24T20:56:26+05:30" level=error msg="\t > spec changes: \n"
time="2023-01-24T20:56:26+05:30" level=error msg="\t > /spec/versions/name=v1/schema/openAPIV3Schema/properties/spec/properties\n"
time="2023-01-24T20:56:26+05:30" level=error msg="\t > - one field removed:\n"
time="2023-01-24T20:56:26+05:30" level=error msg="\t > location:\n"
time="2023-01-24T20:56:26+05:30" level=error msg="\t > type: string\n"
time="2023-01-24T20:56:26+05:30" level=error msg="\t > \n"
time="2023-01-24T20:56:26+05:30" level=error msg="\t > \n"
time="2023-01-24T20:56:26+05:30" level=error msg="\t > \n"
time="2023-01-24T20:56:26+05:30" level=error msg="\t > \n"
time="2023-01-24T20:56:26+05:30" level=error msg="\t > \n"

3. Use the `—force=true` flag to ignore any build failures and obtain successful code generation.
```
nexus datamodel build --name orgchart --force=true
```

</details>