Skip to content

Commit 9f7d6d6

Browse files
JoeavaikathJoeavaikath
committed
Update README
1 parent 5f69fbb commit 9f7d6d6

File tree

3 files changed

+130
-103
lines changed

3 files changed

+130
-103
lines changed

‎README.md‎

Lines changed: 98 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -2,34 +2,35 @@
22

33
[![Cross-Architecture Build Test](https://github.com/migtools/oadp-cli/actions/workflows/cross-arch-build-test.yml/badge.svg)](https://github.com/migtools/oadp-cli/actions/workflows/cross-arch-build-test.yml)
44

5-
A kubectl plugin for working with OpenShift API for Data Protection (OADP) resources, including NonAdminBackup operations.
5+
A kubectl plugin for OpenShift API for Data Protection (OADP) that provides both administrative and non-administrative backup operations.
66

7-
> This project provides a `kubectl` plugin CLI that extends OADP functionality, allowing users to work with both regular Velero resources and NonAdminBackup resources through a unified interface.
7+
> **What it does**: Extends OADP functionality with a unified CLI that supports both cluster-wide Velero operations (admin) and namespace-scoped self-service operations (non-admin users).
88
9-
## Features
9+
## Key Capabilities
1010

11-
- **Regular OADP operations**: Standard Velero backup, restore, and version commands
12-
- **NonAdmin operations**: Create and manage NonAdminBackup resources for namespace-scoped backup operations
13-
- **Automatic namespace detection**: NonAdminBackup automatically uses your current kubectl context namespace
14-
- **Kubectl plugin integration**: Works seamlessly as a kubectl plugin
11+
- **Admin Operations**: Full Velero backup, restore, and version commands (requires cluster admin permissions)
12+
- **Non-Admin Operations**: Namespace-scoped backup operations using non-admin CRDs (works with regular user permissions)
13+
- **Smart Namespace Handling**: Non-admin commands automatically operate in your current kubectl context namespace
14+
- **Seamless Integration**: Works as a standard kubectl plugin
1515

1616
## Command Structure
1717

1818
```
19-
oadp
20-
├── backup (Velero backups)
21-
├── restore (Velero restores)
22-
├── version
23-
└── nonadmin
19+
kubectl oadp
20+
├── backup # Velero cluster-wide backups (admin)
21+
├── restore # Velero cluster-wide restores (admin)
22+
├── version # Version information
23+
└── nonadmin (na) # Namespace-scoped operations (non-admin)
2424
└── backup
25-
└── create
25+
├── create
26+
├── describe
27+
├── logs
28+
└── delete
2629
```
2730

2831
## Installation
2932

30-
### Using Krew (Recommended)
31-
32-
[Krew](https://krew.sigs.k8s.io/) is the recommended way to install kubectl plugins.
33+
### Using Krew (Available soon!)
3334

3435
```sh
3536
# Install Krew if you haven't already
@@ -42,142 +43,136 @@ kubectl krew install oadp
4243
kubectl oadp --help
4344
```
4445

45-
**Note:** The LICENSE file is automatically extracted during Krew installation and available in the plugin directory.
46-
47-
## Build and Install
48-
49-
### Quick Installation
50-
51-
Use the Makefile for easy build and installation:
46+
### Manual Build and Install
5247

5348
```sh
54-
# Build and install the kubectl plugin
49+
# Build and install directly
5550
make install
51+
52+
# Or build manually
53+
make build
54+
sudo mv kubectl-oadp /usr/local/bin/
5655
```
5756

58-
### Manual Installation
57+
## Usage Guide
5958

60-
1. **Build the CLI:**
61-
```sh
62-
make build
63-
```
59+
### Non-Admin Backup Operations
6460

65-
2. **Install as kubectl plugin:**
66-
```sh
67-
sudo mv kubectl-oadp /usr/local/bin/
68-
```
61+
Non-admin commands work within your current namespace and user permissions:
6962

70-
3. **Verify installation:**
71-
```sh
72-
kubectl oadp --help
73-
```
63+
```sh
64+
# Basic backup of current namespace
65+
kubectl oadp nonadmin backup create my-backup
66+
# Short form
67+
kubectl oadp na backup create my-backup
7468

75-
### Development Workflow
69+
# Include specific resource types only
70+
kubectl oadp na backup create app-backup --include-resources deployments,services,configmaps
7671

77-
```sh
78-
# Build and test locally
79-
make build
80-
./kubectl-oadp --help
72+
# Exclude sensitive data
73+
kubectl oadp na backup create safe-backup --exclude-resources secrets
8174

82-
# Run tests
83-
make test
75+
# Preview backup configuration without creating
76+
kubectl oadp na backup create test-backup --snapshot-volumes=false -o yaml
8477

85-
# Check status
86-
make status
78+
# Create backup and wait for completion
79+
kubectl oadp na backup create prod-backup --wait
8780

88-
# View all available commands
89-
make help
81+
# Check backup status
82+
kubectl oadp na backup describe my-backup
83+
84+
# View backup logs
85+
kubectl oadp na backup logs my-backup
86+
87+
# Delete a backup
88+
kubectl oadp na backup delete my-backup
9089
```
9190

92-
### Release Process
91+
### Admin Operations
9392

94-
For maintainers creating releases:
93+
Admin commands require cluster-level permissions and operate across all namespaces:
9594

9695
```sh
97-
# Build release archives for all platforms (includes LICENSE file)
98-
make release
96+
# Cluster-wide backup operations
97+
kubectl oadp backup create cluster-backup --include-namespaces namespace1,namespace2
9998

100-
# Generate Krew plugin manifest with SHA256 checksums
101-
make krew-manifest
99+
# Restore operations
100+
kubectl oadp restore create --from-backup cluster-backup
102101

103-
# Clean up build artifacts
104-
make clean
102+
# Check OADP/Velero version
103+
kubectl oadp version
105104
```
106105

107-
The release process creates:
108-
- Platform-specific archives (`kubectl-oadp-OS-ARCH.tar.gz`) containing the binary and LICENSE file
109-
- SHA256 checksums for each archive
110-
- A Krew plugin manifest file with proper checksums for distribution
111-
112-
## Usage Examples
106+
## How Non-Admin Backups Work
113107

114-
### NonAdminBackup Operations
108+
1. **Namespace Detection**: Commands automatically use your current kubectl context namespace
109+
2. **Permission Model**: Works with standard namespace-level RBAC permissions
110+
3. **Resource Creation**: Creates `Non-admin` custom resources that are processed by the OADP operator
111+
4. **Velero Integration**: OADP operator translates NonAdminBackup resources into standard Velero backup jobs
115112

113+
**Example workflow:**
116114
```sh
117-
# Create a non-admin backup of the current namespace
118-
kubectl oadp nonadmin backup create my-backup
119-
120-
# Create backup with specific resource types
121-
kubectl oadp nonadmin backup create my-backup --include-resources deployments,services
122-
123-
# Create backup excluding certain resources
124-
kubectl oadp nonadmin backup create my-backup --exclude-resources secrets
115+
# Switch to your project namespace
116+
kubectl config set-context --current --namespace=my-project
125117

126-
# View backup YAML without creating it
127-
kubectl oadp nonadmin backup create my-backup --snapshot-volumes=false -o yaml
118+
# Create backup (automatically backs up 'my-project' namespace)
119+
kubectl oadp na backup create project-backup --wait
128120

129-
# Wait for backup completion
130-
kubectl oadp nonadmin backup create my-backup --wait
121+
# Monitor progress
122+
kubectl oadp na backup logs project-backup
131123
```
132124

133-
### Regular OADP Operations
125+
## Development
126+
127+
### Quick Development Commands
134128

135129
```sh
136-
# Work with regular Velero backups
137-
kubectl oadp backup --help
130+
# Build and test locally
131+
make build
132+
./kubectl-oadp --help
138133

139-
# Work with restores
140-
kubectl oadp restore --help
134+
# Run integration tests
135+
make test
141136

142-
# Check version
143-
kubectl oadp version
137+
# Build release archives
138+
make release
139+
140+
# Generate Krew manifest
141+
make krew-manifest
144142
```
145143

146-
## Key Features of NonAdminBackup
144+
### Project Structure
147145

148-
- **Namespace-scoped**: Automatically backs up the namespace where the NonAdminBackup resource is created
149-
- **Simplified workflow**: No need to specify `--include-namespaces` - it uses your current kubectl context
150-
- **Permission-aware**: Works within the permissions of the current user/service account
151-
- **Integration with OADP**: Leverages the underlying Velero infrastructure managed by OADP operator
146+
- **`cmd/`**: Command definitions and CLI logic
147+
- **`cmd/non-admin/`**: Non-admin specific commands
148+
- **`tests/`**: Integration tests and test utilities
149+
- **`Makefile`**: Build automation and common tasks
152150

153151
## Testing
154152

155-
This project includes comprehensive CLI integration tests organized by functionality.
156-
157-
### Quick Test Commands
153+
Comprehensive integration tests verify CLI functionality:
158154

159155
```bash
160156
# Run all tests
161157
make test
162158

163-
# Standard Go pattern (also works)
164-
go test ./...
159+
# For detailed test information
160+
cat tests/README.md
165161
```
166162

167-
📖 **For detailed test documentation, see [tests/README.md](tests/README.md)**
163+
## Technical Details
168164

169-
## Development
165+
**Built with:**
166+
- [Cobra](https://github.com/spf13/cobra) - CLI framework
167+
- [Velero client libraries](https://github.com/vmware-tanzu/velero) - Core backup functionality
168+
- [OADP NonAdmin APIs](https://github.com/migtools/oadp-non-admin) - NonAdminBackup CRD support
170169

171-
This CLI is built using:
172-
- [Cobra](https://github.com/spf13/cobra) for CLI framework
173-
- [Velero client libraries](https://github.com/vmware-tanzu/velero) for core functionality
174-
- [OADP NonAdmin APIs](https://github.com/migtools/oadp-non-admin) for NonAdminBackup operations
170+
**Dependencies:**
171+
- OADP Operator installed in cluster
172+
- Appropriate RBAC permissions for your use case
175173

176174
## License
177175

178-
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
176+
Apache License 2.0 - see [LICENSE](LICENSE) file.
179177

180-
This CLI builds on and integrates with:
181-
- [Velero](https://github.com/vmware-tanzu/velero) (Apache 2.0)
182-
- [OADP](https://github.com/openshift/oadp-operator) (Apache 2.0)
183-
- [Kubernetes](https://github.com/kubernetes/kubernetes) (Apache 2.0)
178+
Integrates with Apache 2.0 licensed projects: [Velero](https://github.com/vmware-tanzu/velero), [OADP](https://github.com/openshift/oadp-operator), [Kubernetes](https://github.com/kubernetes/kubernetes).

‎cmd/non-admin/backup/get.go‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,21 @@
11
package backup
22

3+
/*
4+
Copyright The Velero Contributors.
5+
6+
Licensed under the Apache License, Version 2.0 (the "License");
7+
you may not use this file except in compliance with the License.
8+
You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing, software
13+
distributed under the License is distributed on an "AS IS" BASIS,
14+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
See the License for the specific language governing permissions and
16+
limitations under the License.
17+
*/
18+
319
import (
420
"context"
521
"fmt"

‎cmd/non-admin/backup/logs.go‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,21 @@
11
package backup
22

3+
/*
4+
Copyright The Velero Contributors.
5+
6+
Licensed under the Apache License, Version 2.0 (the "License");
7+
you may not use this file except in compliance with the License.
8+
You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing, software
13+
distributed under the License is distributed on an "AS IS" BASIS,
14+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
See the License for the specific language governing permissions and
16+
limitations under the License.
17+
*/
18+
319
import (
420
"bufio"
521
"compress/gzip"

0 commit comments

Comments
 (0)