Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: restructure build doc #566

Merged
merged 8 commits into from
Apr 20, 2020
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 41 additions & 4 deletions content/docs/using-appsody/building.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,6 @@ The [appsody build](/docs/cli-commands/#appsody-build) command completes the fol

- Extracts your code and other artifacts, including a new Dockerfile, which are required to build the *deployment* image from the *development* image. These files are saved to the `~/.appsody/extract` directory.
- Runs a `docker build` against the Dockerfile that was extracted on the previous step to produce a *deployment* image in your local Docker registry.
- If you want to give the image a name, specify the `-t <tag>` parameter.
- If you want to push the built image to an image repository, specify the `--push` parameter.
- If you run `appsody build` with no parameters, the image is given a name that matches the name of your project.
- Generates a manifest called `app-deploy.yaml` that can be used to deploy your Appsody application.
neeraj-laad marked this conversation as resolved.
Show resolved Hide resolved

> If your project includes uppercase characters, these are converted to lowercase characters in the image name because Docker does not accept uppercase characters in image tags. Also, if your project directory includes underscore characters, those will be converted to dashes (-), because certain areas of Kubernetes are not tolerant of underscore characters.
Expand All @@ -34,4 +31,44 @@ Project extracted to /Users/mchilant/.appsody/extract/appsody-project
Running command: docker[build -t appsody-project -f /Users/mchilant/.appsody/extract/appsody-project/Dockerfile /Users/mchilant/.appsody/extract/appsody-project]
Built docker image appsody-project
Created deployment manifest: /Users/mchilant/appsody-project/app-deploy.yaml
```
```

## Tagging your application image

If you would like to tag your application image with a name, use the following command:
```
neeraj-laad marked this conversation as resolved.
Show resolved Hide resolved
appsody build -t <mynamespace/myrepository[:tag]>
```
This command completes the following actions:

- Calls `appsody build` and creates a deployment image.
- The `-t` flag tags the image with the name `mynamespace/myrepository[:tag]`.

> If you don't specify the `-t` flag, the image is tagged with a name that matches the name of your project.


## Pushing your application image to an image registry

### Pushing to Docker Hub

If you would like to share your images to the Docker Hub registry, use the following command to push your application:
```
appsody build -t <mynamespace/myrepository[:tag]> --push
```
This command completes the following actions:

- Calls `appsody build` and creates a deployment image.
- The `-t` flag tags the image with the name `mynamespace/myrepository[:tag]`.
- The `--push` flag pushes the image to Docker Hub.
- Generates a deployment manifest file named `app-deploy.yaml` in the project directory, if one doesn’t exist already. If a deployment manifest file exists, this command updates the following entries within it: application image, labels, and annotations.

> If you don't specify the `--push` flag, the image is available only on your local Docker registry. The `--push` flag is also available to the [appsody deploy](/docs/using-appsody/deploying) command.

## Pushing to a custom registry
By default, the `--push` flag shares your images to the Docker Hub registry. If you would like to share your images to a custom registry, use the following command to push your application:
```
appsody build -t <mynamespace/myrepository[:tag]> --push-url <registry-url:PORT>
```
The `--push-url` flag pushes the image to a registry URL at a port that you specify with `<registry-url:PORT>`.

> A push is triggered when using the `--push-url` flag even if the `--push` flag is not specified. The `--push` and `--push-url` flags are also available to the [appsody deploy](/docs/using-appsody/deploying) command.
34 changes: 13 additions & 21 deletions content/docs/using-appsody/deploying.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,34 +58,26 @@ This command completes the following actions:
- If you specified the `--knative` flag, or if Knative is the only deployment option for your stack, the command tags the image with the special prefix `dev.local`, making it accessible to your Kubernetes cluster (assuming you followed [these directions](/docs/using-appsody/installing-knative-locally))
- The deployment manifest, `app-deploy.yaml`, is used to issue a `kubectl apply -f` command against the target Kubernetes cluster so that the application can be deployed by the Appsody Operator.

### Deploying your application through Docker Hub
### Deploying to a private registry

If your cluster is configured to pull images from Docker Hub, use the following command to deploy your application:
If you are pulling your image from a registry within your cluster, the registry may only be accessed by using a different name from outside your cluster, and a different name from within your cluster. For example, you might want to push to an external registry and pull from an internal registry.

To specify different push and pull registries, use the following command:
```
appsody deploy -t <mynamespace/myrepository[:tag]> --push --namespace mynamespace [--knative]
appsody deploy -t <mynamespace/myrepository[:tag]> --push-url <external-registry-url:PORT> --pull-url <internal-registry-url:PORT>
```
The command completes the following actions:

- Calls `appsody build` and creates a deployment image, as described in the previous section.
- The `-t mynamespace/myrepository[:tag]` flag tags the image.
- The `--push` flag tells the Appsody CLI to push the image to Docker Hub.
- Creates a deployment manifest file named `app-deploy.yaml` in the project directory, if one doesn’t exist already. If a deployment manifest file exists, this command updates the following entries within it: application image, labels, and annotations. In addition, the `createKnativeService` entry is set to true if you specified the `--knative` flag.
- The Yaml file is used to issue a `kubectl apply -f` command against the target Kubernetes cluster. The Yaml file is set to use the Appsody operator.
- The `--namespace mynamespace` option provisions the deployment under the specified Kubernetes namespace within your cluster.
This command completes the following actions:

> If you don't specify `--push`, the image is available only on your local Docker registry and the target Kubernetes cluster must be configured to have access to your local Docker registry.
- Calls `appsody build` and creates a deployment image.
- The `-t mynamespace/myrepository[:tag]` flag tags the image.
- The `--push-url` pushes the image to `<external-registry-url:PORT>`.
- Generates a deployment manifest file, "app-deploy.yaml", if one is not present, then applies it to your Kubernetes cluster.
- The `--pull-url` injects `<internal-registry-url:PORT>` into the deployment manifest for Kubernetes to pull the correct image.
- Deploys your image to your Kubernetes cluster via the [Appsody operator](/docs/reference/appsody-operator), or as a Knative service if you specify the "--knative" flag.

### Deploying your application to a custom registry
If your cluster is configured to pull images from a custom registry, use the following command to deploy your application:
```
appsody deploy -t <mynamespace/myrepository[:tag]> --push-url <registry-url:PORT>
```
> If an [Appsody operator](/docs/reference/appsody-operator) cannot be found, one will be installed on your cluster.

If you are specifying different push and pull registries, for example, you might want to push to an external registry and pull from an internal registry, use the following command:
```
appsody deploy -t <mynamespace/myrepository[:tag]> --push-url <external-registry-url:PORT> --pull-url <internal-registry-url:PORT>
```
> Note: The pull registry url gets injected into the deployment manifest for Kubernetes to pull the correct image.

### Deploying multiple projects
If you are running multiple Appsody projects on your workstation, you can use `appsody deploy` and `appsody operator` commands to get them deployed to a Kubernetes cluster. However, make sure that you run these commands one at a time, because those commands create temporary files that might lead to conflicts if created concurrently.
Expand Down