docs: add Cozystack v1.x Package-based configuration#412
docs: add Cozystack v1.x Package-based configuration#412IvanHunters wants to merge 2 commits intomainfrom
Conversation
Add comprehensive guide for migrating virtual machines from Proxmox VE to Cozystack. The guide covers disk export, image upload via virtctl, and VM deployment with troubleshooting section. Signed-off-by: ohotnikov.ivan <ohotnikov.ivan@e-queo.net>
Add comprehensive documentation for Cozystack v1.x with Package-based configuration system and restructure installation guides. New documentation: - Package configuration reference with all available options - v1.x installation guide using Package resource - Landing page with version selection - Migration guide from v0.x ConfigMap to v1.x Package - Runtime configuration examples with kubectl patch Restructured installation guides: - Created install-cozystack/ directory with version subpages - Main page explains differences and helps choose version - v1.x guide marked as "Recommended" - v0.x guide marked as "Legacy" Configuration documentation: - v1.x Package guide (weight: 5) - recommended approach - v0.x ConfigMap guide (weight: 10) - legacy reference - Both marked with version labels and cross-references Bundle variants in v1.x: - isp-full: full platform with all system components - isp-hosted: hosted variant without system components - distro-full: distribution variant Signed-off-by: ohotnikov.ivan <ohotnikov.ivan@e-queo.net>
✅ Deploy Preview for cozystack ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Summary of ChangesHello @IvanHunters, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the Cozystack documentation by introducing detailed guides for the new v1.x Package-based configuration. It reorganizes the installation process to provide clear version-specific instructions and includes a comprehensive reference for the v1.x configuration model. Additionally, a new guide for migrating virtual machines from Proxmox to Cozystack is added, improving the platform's interoperability and user onboarding experience. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly improves the documentation by adding guides for the new Cozystack v1.x Package-based configuration and restructuring the installation guides for better version navigation. The new documentation is comprehensive and covers installation, configuration, and migration. My review focuses on ensuring consistency and correctness, particularly in distinguishing between v0.x (ConfigMap) and v1.x (Package) configurations. I've identified several instances where v0.x commands and concepts were used in the new v1.x guides, which could lead to confusion and misconfiguration. I've provided suggestions to correct these to align with the v1.x Package-based approach. Additionally, I've made a few suggestions to improve clarity and consistency throughout the new documentation pages.
| First, patch the ConfigMap with IPs to expose: | ||
|
|
||
| ```bash | ||
| kubectl patch -n cozy-system configmap cozystack --type=merge -p '{ | ||
| "data": { | ||
| "expose-external-ips": "192.168.100.11,192.168.100.12,192.168.100.13" | ||
| } | ||
| }' | ||
| ``` |
There was a problem hiding this comment.
This section incorrectly instructs the user to patch a ConfigMap, which is a v0.x configuration method. For v1.x, configuration should be done by patching the Package resource. Using the wrong command will lead to misconfiguration.
First, patch the Package with IPs to expose:
```bash
kubectl patch package cozystack.cozystack-platform -n cozy-system --type merge -p '{
"spec": {
"components": {
"platform": {
"values": {
"publishing": {
"externalIPs": [
"192.168.100.11",
"192.168.100.12",
"192.168.100.13"
]
}
}
}
}
}
}'| If you left this line in the ConfigMap, Cozystack Dashboard must be already available at this moment: | ||
|
|
||
| ```yaml | ||
| data: | ||
| expose-services: "dashboard,api" | ||
| ``` |
There was a problem hiding this comment.
This section incorrectly refers to ConfigMap and shows a ConfigMap data structure, which is for v0.x. For v1.x, this should refer to the Package resource and its publishing.exposedServices field. For example:
spec:
components:
platform:
values:
publishing:
exposedServices:
- dashboard
- api| ```bash | ||
| kubectl patch -n cozy-system cm cozystack --type=merge -p '{"data":{ | ||
| "expose-services": "dashboard" | ||
| }}' | ||
| ``` |
There was a problem hiding this comment.
This command patches a ConfigMap (cm), which is for v0.x. For v1.x, you should patch the Package resource to update exposedServices.
| ```bash | |
| kubectl patch -n cozy-system cm cozystack --type=merge -p '{"data":{ | |
| "expose-services": "dashboard" | |
| }}' | |
| ``` | |
| kubectl patch package cozystack.cozystack-platform -n cozy-system --type merge -p '{ | |
| "spec": { | |
| "components": { | |
| "platform": { | |
| "values": { | |
| "publishing": { | |
| "exposedServices": ["dashboard"] | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }' |
| - Modify your Cozystack ConfigMap to enable `cdi-uploadproxy`: | ||
| ```bash | ||
| kubectl patch cm -n cozy-system cozystack --type merge -p='{"data":{ | ||
| "expose-services": "dashboard,cdi-uploadproxy" | ||
| }}' | ||
| ``` |
There was a problem hiding this comment.
This command uses kubectl patch cm to patch a ConfigMap, which is the configuration method for Cozystack v0.x. This guide should provide instructions for v1.x, which uses a Package resource. Please update the command to patch the Package resource or clarify which Cozystack version this guide applies to.
| - Modify your Cozystack ConfigMap to enable `cdi-uploadproxy`: | |
| ```bash | |
| kubectl patch cm -n cozy-system cozystack --type merge -p='{"data":{ | |
| "expose-services": "dashboard,cdi-uploadproxy" | |
| }}' | |
| ``` | |
| - Modify your Cozystack Package to enable `cdi-uploadproxy`: | |
| ```bash | |
| kubectl patch package cozystack.cozystack-platform -n cozy-system --type merge -p='{ | |
| "spec": { | |
| "components": { | |
| "platform": { | |
| "values": { | |
| "publishing": { | |
| "exposedServices": ["dashboard", "cdi-uploadproxy"] | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }' | |
| ``` |
| - Configure the CDI upload proxy endpoint in your Cozystack values: | ||
| ```yaml | ||
| values-cdi: | | ||
| uploadProxyURL: https://cdi-uploadproxy.example.org | ||
| ``` |
There was a problem hiding this comment.
The instruction to configure uploadProxyURL is unclear. The values-cdi: syntax is for a v0.x ConfigMap. For v1.x, this configuration should be part of the Package resource. Please clarify how to set this value for v1.x, for example by showing how to patch the Package resource under spec.components.<component-name>.values.
| joinCIDR: "100.64.0.0/16" | ||
| publishing: | ||
| host: "example.org" | ||
| apiServerEndpoint: "https://192.168.1.10:6443" |
There was a problem hiding this comment.
The apiServerEndpoint in this minimal example uses an IP address, which is inconsistent with other examples in the documentation (e.g., in v1.md and the full example in this file) that use a domain name like api.example.org. Using a domain name is generally better practice. For consistency, please update this to use api.example.org.
| apiServerEndpoint: "https://192.168.1.10:6443" | |
| apiServerEndpoint: "https://api.example.org:6443" |
| ```bash | ||
| kubectl get package cozystack.cozystack-platform -n cozy-system \ | ||
| -o jsonpath='{.spec.components.platform.values}' | yq | ||
| ``` |
There was a problem hiding this comment.
The command uses yq, which is a third-party tool that might not be installed on the user's system. It's good practice to either mention yq as a prerequisite or provide an alternative. Consider adding a note for the user to install yq.
|
|
||
| | v0.x ConfigMap Key | v1.x Package Path | | ||
| |--------------------|-------------------| | ||
| | `bundle-name: paas-full` | `spec.variant: isp-full` | |
There was a problem hiding this comment.
The mapping for bundle-name is very specific. It would be more helpful to explain the general mapping rule for bundle names from v0.x to v1.x (e.g., paas-full -> isp-full, paas-hosted -> isp-hosted) or make the table entry more generic.
| | `bundle-name: paas-full` | `spec.variant: isp-full` | | |
| | `bundle-name: paas-*` | `spec.variant: isp-*` (e.g., `paas-full` -> `isp-full`) | |
| ```bash | ||
| kubectl apply -f vmdisk-upload.yaml | ||
| ``` |
There was a problem hiding this comment.
The filename vmdisk-upload.yaml is used in this command, but its content is not defined earlier. It would be helpful to instruct the user to create this file with the YAML content provided in the preceding code block.
| ```bash | ||
| kubectl apply -f vminstance.yaml | ||
| ``` |
There was a problem hiding this comment.
Similar to the previous step, the filename vminstance.yaml is used here without being defined. Please add instructions for creating this file with the YAML content from the preceding block.
1 participant
Summary
Adds comprehensive documentation for Cozystack v1.x Package-based configuration system and restructures installation guides for better version navigation.
New Documentation
Package Configuration Reference
Location:
content/en/docs/operations/configuration/package.mdComplete reference for v1.x Package resource:
isp-full,isp-hosted,distro-fullkubectl patchInstallation Guide Structure
Location:
content/en/docs/getting-started/install-cozystack/Restructured installation guides with version selection:
_index.md) - helps users choose between versionsv1.md) - Package-based configuration (Recommended)v0.md) - ConfigMap-based configuration (Legacy)Key Features
Version Navigation
Package Configuration
Migration Support
Documentation Structure
Menu Organization
Updated Files
content/en/docs/operations/configuration/configmap.md- marked as v0.x, added v1.x referencecontent/en/docs/getting-started/install-cozystack/v0.md- renamed and marked as legacycontent/en/docs/getting-started/install-cozystack/v1.md- new v1.x installation guidecontent/en/docs/getting-started/install-cozystack/_index.md- new landing pagecontent/en/docs/operations/configuration/package.md- new Package configuration referenceChecklist