Working on VMware Spring Cloud Data Flow for Kubernetes Documentation

The VMware Spring Cloud Data Flow for Kubernetes documentation is now published on docs.vmware.com. See below for information about how the documentation is stored and published and about the toolchain we now use.

Branch/version map

| Branch | Status | URL |

|--------|------------|-----|

| main | develop | |

| v1.6 | published | https://docs.vmware.com/en/VMware-Spring-Cloud-Data-Flow-for-Kubernetes/1.6/scdf-k8s/GUID-index.html |

| v1.5 | published | https://docs.vmware.com/en/VMware-Spring-Cloud-Data-Flow-for-Kubernetes/1.5/scdf-k8s/GUID-index.html |

| v1.4 | published | https://docs.vmware.com/en/VMware-Spring-Cloud-Data-Flow-for-Kubernetes/1.4/scdf-k8s.pdf |

| v1.3 | published | https://docs.vmware.com/en/VMware-Spring-Cloud-Data-Flow-for-Kubernetes/1.3/scdf-k8s.pdf |

| v1.2 | published | https://docs.vmware.com/en/VMware-Spring-Cloud-Data-Flow-for-Kubernetes/1.2/scdf-k8s.pdf |

If You Previously Worked With Bookbinder and Concourse

We no longer use:

The "book" repository (https://github.com/pivotal-cf/docs-book-scdf-k8s)
Bookbinder
The Concourse pipeline (https://runway-ci.eng.vmware.com/teams/mapbu-docs/pipelines/cf-services?group=scdf-k8s)
The Pivotal Docs staging website (https://docs-pcf-staging.sc2-04-pcf1-apps.oc.vmware.com/scdf-k8s)
The Pivotal Docs production website (https://docs.pivotal.io/scdf-k8s)

Requirements

You will need:

The docs content repository (https://github.com/pivotal-cf/docs-spring-cloud-dataflow-k8s). Note that this is NOT the "book" repository
The Markdown Local Preview CLI utility (if you want to view your changes locally)
Access to DocWorks (https://docworks.vmware.com/). Ask for access in the #vmdocs-markdown Slack channel
Access to the Docs Dashboard (https://docsdash.vmware.com/). Ask for access in the #vmdocs-markdown Slack channel

Workflow

Complete steps:

Edit content files locally
Preview your changes locally
Commit and push your changes to GitHub
In DocWorks, publish the docs to staging
Review your changes on staging
In Docs Dashboard, promote your changes to pre-production
In Docs Dashboard, sign off on your changes in pre-production
In Docs Dashboard, promote your changes to production

For more information, see the following sections.

Editing Content Files

All content files are stored in the content repository on GitHub (https://github.com/pivotal-cf/docs-spring-cloud-dataflow-k8s). Clone this repository.

To edit documentation, check out the relevant branch, make changes locally, preview if desired (see the next section), then commit and push your changes. For example, to edit documentation for Spring Cloud Data Flow version 1.4, check out and commit changes to the v1.4 branch.

Previewing Your Changes Locally

To preview your changes locally, you must install the Markdown Local Preview CLI utility. For more information and the file download link, see Using the Markdown Local Preview CLI Utility on Confluence.

Preparing for Local Previews

After installing the utility, follow these steps to prepare for local previews:

From the utility directory (for example, ~/Downloads/VMware.GTIX.MarkdownCLI-osx-x64-1.0-0.markdown-cli-osx/Markdown-Cli/), run the Markdown-Cli utility:
```
$ ./Markdown-Cli
```
Select Build Project (watches for changes), then press Enter.
Enter the complete path to the docs content repository on your local machine. For example:
```
/Users/bobcratchit/Work/docs-spring-cloud-dataflow-k8s
```
Type n, then press Enter.
Press any key.
Select Back, then press Enter.
Select Exit, then press Enter.
In your IDE or text editor, open the newly-generated file _md-cli/dist/config.json.
Set tocLocation to toc.md.
Set variablesLocation to variables.yml.

Previewing Changes

Now you can preview your changes:

From the utility directory, run the Markdown-Cli utility:
```
$ ./Markdown-Cli
```
Select Build Project (watches for changes), then press Enter.
Enter the complete path to the docs content repository on your local machine. For example:
```
/Users/bobcratchit/Work/docs-spring-cloud-dataflow-k8s
```
Type y, then press Enter.
In a browser, open the DocsPreview.html file that the utility generated under a _md-cli subdirectory of the content repository directory. The file path will be something like the following:
```
/Users/bobcratchit/Work/docs-spring-cloud-dataflow-k8s/_md-cli/dist/DocsPreview.html
```
Navigate to the page that you edited.
If you make additional changes, the utility will automatically regenerate the preview. You will have to refresh the preview page in your browser, then navigate to your edited page again.

Publishing to Staging and Promoting to Pre-Production

To publish your changes on the staging website:

Visit DocWorks (https://docworks.vmware.com/).
Log in using your VMware LDAP credentials.
From the main navigation menu, select Markdown.
In the left-hand navigation menu, under Markdown Projects, click All.
Search for the docs set (for example, "Spring Cloud Data Flow").
Locate the "card" for the docs set and click Publish.

Note
Depending on the project, you may see Build and Deploy buttons instead of a Publish button. If so, first click Build, then when the build has finished, click Deploy.
If the build fails, click the red bar representing the most recent build and review the logs for any warnings or errors. Resolve any errors and start a new build.
When the build succeeds, visit the Docs Dashboard (https://docsdash.vmware.com/).
Log in using your VMware LDAP credentials.
From the main navigation menu, select Deployment > Stage.
In the list of deployments, locate the project and click its link in the Publication column. This will take you to the staging website, where you can view your changes.

When you are satisfied with your changes on staging:

Return to the Docs Dashboard.
In the list of deployments, select your project (select the checkbox in the Product column).
Click the Deploy Selected to Pre-Prod button.
In the Deployment Status dialog, click Refresh to update the status of the deployment. When the deployment has succeeded, click Hide.
From the main navigation menu, select Deployment > Pre Prod.
In the list of deployments, locate the project and click its link in the Publication column. This will take you to the pre-production website, where you can view your changes.

Promoting to Production

When you are satisfied with your changes in pre-production:

Return to the Docs Dashboard.
In the list of deployments, select your project in the Product column).
Click the Sign-Off For Release button.
Confirm your sign-off.
In the list of deployments, select your project again.
Click the Deploy Selected to Prod button.
Confirm that you want to deploy to production.
In the Deployment Status dialog, click Refresh to update the status of the deployment. When the deployment has succeeded, click Hide.
From the main navigation menu, select Deployment > Production.
In the list of deployments, locate the project and click its link in the Publication column. This will take you to the production website, where you can view your published changes.

Document how to configure "keystore" for SCDF and Skipper

To enable HTTPS (SSL), one needs to add the keystore that is accessible by the application.

Oded Shopen 2:24 AM
One issue I'm facing is how to transfer the keystore contents to the application.yaml. The security section here: https://docs.pivotal.io/scdf-k8s/0-1/configuring-installation-values.html redirects you to the SCDF documentation, but that expects you to run on your own machine and not as pods on Kubernetes. So, just adding the path to the keystore file will not work because that path doesn't exist inside the pod. I guess I could add it as a volume mount to the pod but I think this should be documented.
Caused by: java.io.FileNotFoundException: /home/odedia/scdf/dataflow.keystore (No such file or directory)

Resolved with this:

kubectl create configmap keystore --from-file=/home/odedia/scdf/dataflow.keystore
Then modified ./apps/data-flow/kustomize/overlays/dev/deployment-patch.yaml as follows:
metadata:
  name: scdf-server
spec:
  template:
    spec:
      containers:
      - name: scdf-server
        volumeMounts:
          - name: database
            mountPath: /etc/secrets/database
            readOnly: true
          - name: keystore 
            mountPath: /etc/secrets/keystore
            readOnly: true
      imagePullSecrets:
      - name: scdf-image-regcred
      volumes:
        - name: database
          secret:
            secretName: postgresql
            items:
            - key: postgresql-password
              path: database-password
        - name: keystore
          configMap:
            name: keystore

And then application.yml defines: key-store: "/etc/secrets/keystore/dataflow.keystore"

pivotal-cf / docs-spring-cloud-dataflow-k8s Goto Github PK

docs-spring-cloud-dataflow-k8s's Introduction

Working on VMware Spring Cloud Data Flow for Kubernetes Documentation

Branch/version map

If You Previously Worked With Bookbinder and Concourse

Requirements

Workflow

Editing Content Files

Previewing Your Changes Locally

Preparing for Local Previews

Previewing Changes

Publishing to Staging and Promoting to Pre-Production

Promoting to Production

docs-spring-cloud-dataflow-k8s's People

Contributors

Watchers

Forkers

docs-spring-cloud-dataflow-k8s's Issues

Notable Changes

Notable changes

Library updates

Kubernetes

Notable Changes

Notable Changes

Cleanup

Find all components that we need to Cleanup

Cleanup SCDF bits (you will need to update the services below, this is just an example)

Cleanup Skipper

Cleanup Rabbitmq

Cleanup postgres

Notable Changes

Issues

Recommend Projects

Recommend Topics

Recommend Org