Skip to content

Commit 39c7e3b

Browse files
SuselzSuselz
authored
Add signature migration tool (#245)
Signed-off-by: suselz <[email protected]>
1 parent 8832f05 commit 39c7e3b

File tree

6 files changed

+1359
-0
lines changed

6 files changed

+1359
-0
lines changed

‎internal/tools/sigmigrate/README.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# sig-migrate
2+
3+
Subcommand for migrating Kubernetes resources by adding and removing migration annotations.
4+
5+
## Description
6+
7+
The `sig-migrate` command collects all Kubernetes resources (both namespaced and cluster-wide), adds a `d8-migration=<timestamp>` annotation, and then removes annotations with the `d8-migration-` prefix. This is useful for triggering reconciliation in Deckhouse controllers.
8+
9+
## Usage
10+
11+
```shell
12+
d8 tools sig-migrate [flags]
13+
```
14+
15+
## Flags
16+
17+
| Flag | Description | Default |
18+
| -------------- | ---------------------------------------------------------------------------- | ------------------------------------------- |
19+
| `--retry` | Retry annotation for objects that failed to be processed in the previous run | `false` |
20+
| `--as` | Specify a Kubernetes service account for kubectl operations (impersonation) | `system:serviceaccount:d8-system:deckhouse` |
21+
| `--log-level` | Set the log level (INFO, DEBUG, TRACE) | `DEBUG` |
22+
| `--kubeconfig` | Path to the kubeconfig file to use for CLI requests | `$HOME/.kube/config` or `$KUBECONFIG` |
23+
| `--context` | The name of the kubeconfig context to use | `kubernetes-admin@kubernetes` |
24+
25+
## Usage Examples
26+
27+
### Basic Usage
28+
29+
Run migration for all resources in the cluster:
30+
31+
```shell
32+
d8 tools sig-migrate
33+
```
34+
35+
### With kubeconfig and context
36+
37+
```shell
38+
d8 tools sig-migrate --kubeconfig ~/.kube/config --context my-cluster
39+
```
40+
41+
### With a different service account
42+
43+
Use a different service account for operations:
44+
45+
```shell
46+
d8 tools sig-migrate --as system:serviceaccount:my-namespace:my-serviceaccount
47+
```
48+
49+
### Retry for failed objects
50+
51+
Retry annotation for objects that failed to be processed in the previous run:
52+
53+
```shell
54+
d8 tools sig-migrate --retry
55+
```
56+
57+
### With verbose logging
58+
59+
Enable verbose logging (TRACE level):
60+
61+
```shell
62+
d8 tools sig-migrate --log-level TRACE
63+
```
64+
65+
### Combined example
66+
67+
```shell
68+
d8 tools sig-migrate \
69+
--kubeconfig ~/.kube/config \
70+
--context production \
71+
--as system:serviceaccount:d8-system:deckhouse \
72+
--log-level DEBUG
73+
```
74+
75+
## How It Works
76+
77+
1. **Resource Collection**: The command uses Kubernetes API discovery to automatically discover all available resources (both namespaced and cluster-wide).
78+
79+
2. **Adding Annotation**: For each resource, an annotation `d8-migration=<timestamp>` is added, where `timestamp` is the current time in Unix timestamp format.
80+
81+
3. **Removing Annotations**: After adding the new annotation, all annotations starting with the `d8-migration-` prefix are removed.
82+
83+
4. **Error Handling**:
84+
- If a resource does not support annotations (MethodNotAllowed), it is added to the list of unsupported types and skipped in the future.
85+
- If the operation is forbidden for the current service account, the command automatically attempts to use an alternative service account (`system:serviceaccount:d8-multitenancy-manager:multitenancy-manager`).
86+
- All failed attempts are recorded in `/tmp/failed_annotations.txt` and `/tmp/failed_errors.txt` files for subsequent retry.
87+
88+
## Retry Files
89+
90+
The command creates two files to track failed operations:
91+
92+
- `/tmp/failed_annotations.txt` - list of objects in `namespace|name|kind` format that failed to be processed
93+
- `/tmp/failed_errors.txt` - detailed error information in `namespace|name|kind|error_message` format
94+
95+
### Automatic Failure Detection
96+
97+
At the end of execution, if any objects failed to be annotated, the command will automatically display a warning message with:
98+
99+
- The number of failed objects
100+
- Paths to both error log files
101+
- Instructions on how to investigate and retry
102+
103+
Example output when failures occur:
104+
105+
```
106+
⚠️ Migration completed with 5 failed object(s).
107+
108+
Some objects could not be annotated. Please check the error details:
109+
Error log file: /tmp/failed_errors.txt
110+
Failed objects list: /tmp/failed_annotations.txt
111+
112+
To investigate the issues:
113+
1. Review the error log file to understand why objects failed
114+
2. Check permissions and resource availability
115+
3. Retry migration for failed objects only using:
116+
d8 tools sig-migrate --retry
117+
```
118+
119+
To retry failed objects, use the `--retry` flag:
120+
121+
```shell
122+
d8 tools sig-migrate --retry
123+
```
124+
125+
## Log Levels
126+
127+
- **INFO**: Minimal output, only important messages
128+
- **DEBUG**: Detailed output with progress information (default)
129+
- **TRACE**: Maximum verbose output, including all commands and API responses
130+
131+
## Limitations
132+
133+
- Some resource types may not support annotations (e.g., some CRDs). Such types are automatically detected and skipped.
134+
- The command requires appropriate access rights to annotate resources in the cluster.
135+
- For large clusters, execution may take a significant amount of time.
136+
137+
## Notes
138+
139+
- The command uses impersonation to perform operations on behalf of the specified service account.
140+
- All operations are performed sequentially to ensure stability.
141+
- Execution progress is displayed in real-time with completion percentage.
142+
143+
## See Also
144+
145+
- [d8 tools](https://github.com/deckhouse/deckhouse-cli) - other tools in the tools category
146+
- [Deckhouse Documentation](https://deckhouse.io/) - Deckhouse Kubernetes Platform documentation

‎internal/tools/sigmigrate/cmd/flags.go‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
/*
2+
Copyright 2025 Flant JSC
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package cmd
18+
19+
import (
20+
"os"
21+
22+
"github.com/spf13/pflag"
23+
)
24+
25+
func addFlags(flags *pflag.FlagSet) {
26+
flags.Bool(
27+
"retry",
28+
false,
29+
"Retry annotation for previously failed objects.",
30+
)
31+
32+
flags.String(
33+
"as",
34+
"system:serviceaccount:d8-system:deckhouse",
35+
"Specify a Kubernetes service account for the kubectl operations (impersonation).",
36+
)
37+
38+
flags.String(
39+
"log-level",
40+
"DEBUG",
41+
"Set the log level (INFO, DEBUG, TRACE). Defaults to DEBUG.",
42+
)
43+
44+
defaultKubeconfigPath := os.ExpandEnv("$HOME/.kube/config")
45+
if p := os.Getenv("KUBECONFIG"); p != "" {
46+
defaultKubeconfigPath = p
47+
}
48+
49+
flags.String(
50+
"kubeconfig",
51+
defaultKubeconfigPath,
52+
"Path to the kubeconfig file to use for CLI requests. (default is $KUBECONFIG when it is set, $HOME/.kube/config otherwise)",
53+
)
54+
55+
flags.String(
56+
"context",
57+
"kubernetes-admin@kubernetes",
58+
"The name of the kubeconfig context to use.",
59+
)
60+
}

‎internal/tools/sigmigrate/cmd/sigmigrate.go‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
/*
2+
Copyright 2025 Flant JSC
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package cmd
18+
19+
import (
20+
"github.com/spf13/cobra"
21+
"k8s.io/kubectl/pkg/util/templates"
22+
23+
"github.com/deckhouse/deckhouse-cli/internal/tools/sigmigrate"
24+
)
25+
26+
var sigMigrateLong = templates.LongDesc(`
27+
Migrate Kubernetes resources by adding and removing migration annotations.
28+
29+
This command collects all Kubernetes resources (both namespaced and cluster-wide),
30+
adds a migration annotation (d8-migration=<timestamp>), and then removes the
31+
d8-migration- annotation prefix. This is useful for triggering reconciliation
32+
in Deckhouse controllers.
33+
34+
The command supports:
35+
- Retrying failed annotations from previous runs
36+
- Using different service accounts via impersonation
37+
- Configurable log levels (INFO, DEBUG, TRACE)
38+
39+
© Flant JSC 2025`)
40+
41+
func NewCommand() *cobra.Command {
42+
sigMigrateCmd := &cobra.Command{
43+
Use: "sig-migrate",
44+
Short: "Migrate Kubernetes resources by adding and removing migration annotations",
45+
Long: sigMigrateLong,
46+
RunE: sigmigrate.SigMigrate,
47+
}
48+
49+
addFlags(sigMigrateCmd.Flags())
50+
51+
return sigMigrateCmd
52+
}

0 commit comments

Comments
 (0)