hazelcast / hazelcast-platform-operator-docs

Source content for the Kubernetes Operator of Hazelcast Platform (Enterprise)

Documentation for Hazelcast Platform Operator

This repository contains the Antora components for the Hazelcast Platform Operator documentation.

The documentation source files are marked up with AsciiDoc.

Docs Structure

This section describes some important information about how this repository is structured:

• The component name, version, and start page are configured in each branch’s antora.yml file.

• The navigation for all modules is stored in the ROOT module’s nav.adoc file.

• The docs site playbook instructs Antora to automatically build the site using content in the main branch as well as any branches that are prefixed with v/.

Release Workflow

Documentation for new releases is hosted in versioned branches that are prefixed with v/. The latest-dev content (snapshot content) is stored in the main branch.

We support documentation for the latest patch releases of minor versions. For example, content for the 5.0 version is hosted in the v/5.0 branch. This branch contains content for the latest patch release of version 5.0.

Note	The documentation build process is triggered whenever you create a new branch with the v/ prefix, push to an existing v/ branch, or push to the main branch.

Creating Release Branches

1. If you are releasing a new major version, create a release branch from the main branch.

   For example, if you are releasing version 5.1, create a new release branch named 5.1 from the main branch.

2. Update the fields mentioned in Latest Releases.

3. Remove the prerelease: true field from the docs/antora.yml file of the hz-docs repository.

   Important

   If you are creating a branch for a beta release, do not remove this field.

4. When you are ready to release, create a maintenance branch (v/<version>) from the release branch.

   Note	As soon as you push the maintenance branch to the repository, GitHub will trigger a new build of the site, which will include your new content.

5. Make sure to delete the release branch.

   For example, if you released version 5.1, delete the 5.1 branch. This step helps to keep the repository clean of release branches.

Latest Releases

Add the major.minor version to the following:

Repository	Branch	File	Fields
hazelcast-platform-operator-docs	v/{major.minor version}	docs/antora.yml	version display_version
hazelcast-docs	main and develop	_redirects	/hazelcast-operator/latest/*
		search-config.json	Create a new object in the start_urls array. { "url": "https://docs.hazelcast.com/hazelcast-operator/(?P<version>.*?)/", "tags": [ "hazelcast-operator-{major.minor version}" ], "variables": { "version": ["{major.minor version}"] }, "selectors_key": "operator" }

Add the full version major.minor.patch to the following:

Repository	File	Fields
hazelcast-platform-operator-docs	docs/antora.yml	full-version

Patch Releases

In the v/ branch for the minor version whose patch you are releasing, update the asciidoc.attributes.full-version field in the antora.yml file to the new patch version. For example, if you are releasing version 5.0.3, find the v/5.0 branch and update the asciidoc.attributes.full-version field in the antora.yml file with 5.0.3.

Note	As soon as you push content to this branch, GitHub will trigger a new build of the site, which will include your new content.

GitHub Actions

To automate some elements of the build process, this repository includes the following GitHub Actions:

Table 1. GitHub Actions

File	Description	Triggers
validate-site.yml	Validates that all internal and external links are working	On a pull request to the main branch and v/ maintenance branches
build-site.yml	Builds the production documentation site by sending a build hook to Netlify (the hosting platform that we use)	On a push to the main branch and any v/ maintenance branches

Contributing

If you want to add a change or contribute new content, see our contributing guide.

To let us know about something that you’d like us to change, consider creating an issue.

License

All documentation is available under the terms of a Creative Commons License

hazelcast-platform-operator-docs's Issues

Docs: Feedback for Deploy a Cluster with the Hazelcast Platform Operator for Kubernetes

Hi, I have some feedback about this page

In Step 2 - we ask users to create hazelcast.yaml.

In the Open Source example, this is fine.
In the Enterprise example, this breaks as we ask for:

kubectl apply -f hazelcast-enterprise.yaml

Can we be consistent? Either use hazelcast.yaml everywhere - or ensure it's clear that there is need for one or the other?

Docs: Feedback for Deploy a Cluster with the Hazelcast Platform Operator for Kubernetes

Hi, I have some feedback about this page

• Should be a prerequisite about having Helm
• Substep 3 of Step 2 does not work. (Error from server (NotFound): pods "hazelcast-sample-0" not found)
• Nevertheless, kubectl get hazelcast shows that cluster is up and running.
• Substep 3 in Step 2, and Step 3 both talk about verifying/checking if the cluster is running. I think a rewording is needed in Substep 3 of Step 2 (e.g., "to see the member information", or alike)..

Docs: Feedback for Configuring the Hazelcast Serialization

Hi, I have some feedback about this page

Lets put Compact Serialization first - to ensure it aligns with the Platform Serialization documentation.

Also - I presume Hazelcast CR = Hazelcast Custom Resource?

Docs: Feedback for User Code Deployment

Hi, I have some feedback about this page

The discription for bucketURI and secretName is inverted

Confusing info box in the Operator documentation

The Getting Started guide has this infobox:

I find the text confusing. When it can be inaccurate? Is it just "check-then-act"? What does "informational purposes" means exactly? What is the use-case where I can use this field and when I should NOT rely on it?

Documentation: Misleading check

I could not validate this due to hazelcast/hazelcast-platform-operator#98, but I believe the Getting Started guide has a wrong step. It looks like this:

See the 3rd step: kubectl logs pod/hazelcast-sample-0. I don't know where is the pod name coming from. Given the CR has

metadata:
  name: hazelcast

I guess it should have been kubectl logs pod/hazelcast-0 ?

Related issue: https://github.com/hazelcast/hazelcast-platform-operator/issues/99

Docs: Feedback for Deploy a Cluster with the Hazelcast Platform Operator for Kubernetes

Hi, I have some feedback about this page

Instruction step 2, to install an operator fails if the cluster is not up and running at localhost:8080

Can we add instructions on how to get a K8s / Openshift cluster up and running too?

Docs: Feedback for Deploy a Cluster with the Hazelcast Platform Operator for Kubernetes

Hi, I have some feedback about this page

Missing instructions on how to install/setup HELM as this is then used in the guide all the way through.

Docs: Feedback for Deploy a Cluster with the Hazelcast Platform Operator for Kubernetes

Hi, I have some feedback about this page

We make reference to CRDs.

But don't explain that this is a Custom Resource Definition. Should we introduce customers / users/ readers to acronyms before using them?

Documentation: Inconsistent example between OSS and EE deployments

The Getting Started guide has tabs for deploying OSS and EE versions. They look like this:

As you can see there are other differences than OSS vs EE. For example the EE tab set clusterSize and version explicitly while OSS relies on defaults. I find this confusing, as a user I would expect OSS vs EE to be the only difference.

I think the OSS should have at least the clusterSize and version added. Currently the CR definition does not have the spec section at all. So when I wanted to add an explicit Hazelcast I ended-up with this:

apiVersion: hazelcast.com/v1alpha1
kind: Hazelcast
metadata:
  name: hazelcast-sample
  clusterSize: 3

Obviously this did not work, because the clusterSize does not belong to the metadata section.

Docs: Feedback for User Code Deployment

Hi, I have some feedback about this page

The page is missing how the secret should be created.

For example what there is in backup-restore

Wrong metdata:name for Open Source documentation

STR:

1. Open https://docs.hazelcast.com/operator/latest/get-started#:~:text=apiVersion%3A%20hazelcast.com/v1alpha1%0Akind%3A%20Hazelcast%0Ametadata%3A%0A%20%20name%3A%20hazelcast
2. Check the metadata name

metadata: name: hazelcast

3. Verify the command to read the logs https://docs.hazelcast.com/operator/latest/get-started#:~:text=kubectl%20logs%20pod/hazelcast%2Dsample%2D0

ER:
There metadata-name should be hazelcast-sample because reading the logs is performed by the next command kubectl logs pod/hazelcast-sample-0
AR:
The example is using the name hazelcast. Hence reading the logs doesn't works
metadata: name: hazelcast

Docs: Feedback for Persistence, Backup and Restore

Hi, I have some feedback about this page

Error from server (BadRequest): error when replacing "hazelcast-enterprise.yaml": Hazelcast in version "v1alpha1" cannot be handled as a Hazelcast: strict decoding error: unknown field "spec.persistence.baseDir"

Operator 5.10 looks to have an error when enabling persistence that it doesn't like the spec baseDir?

'''
spec:
persistence:
baseDir: "/data/hot-restart/"
clusterDataRecoveryPolicy: "FullRecoveryOnly"
'''

Docs: Feedback for Deploy a Cluster with the Hazelcast Platform Operator for Kubernetes

Hi, I have some feedback about this page

> kg pods
+ kubectl get pods
NAME                                                     READY   STATUS    RESTARTS   AGE
hazelcast-0                                              1/1     Running   0          116s
hazelcast-1                                              1/1     Running   0          32s
hazelcast-2                                              1/1     Running   0          29s
hazelcast-platform-controller-manager-6b6d888459-b9ljx   1/1     Running   0          3m57s

The actual pod name created as hazecast-0. But guide says kubectl logs pod/hazelcast-sample-0 for checking the logs of member. There is a conflict I guess. 🤔