使用 Skipper
本节是 Skipper 的 “'三小时游览'”。 它详细描述了如何配置和使用 Skipper 的主要功能集。 我们将介绍 shell、平台、软件包和存储库。
欢迎在 Stack Overflow 上提问。 可以在 Github issues 上提交问题。
12. 船长壳
该 shell 基于 Spring Shell 项目。
shell 的两个最佳功能是 Tab 键补全和命令着色。
使用 'help' 命令或--help
参数以获取帮助信息。
使用--help
参数如下:
Skipper Options:
--spring.cloud.skipper.client.serverUri=<uri> Address of the Skipper Server [default: http://localhost:7577].
--spring.cloud.skipper.client.username=<USER> Username of the Skipper Server [no default].
--spring.cloud.skipper.client.password=<PASSWORD> Password of the Skipper Server [no default].
--spring.cloud.skipper.client.credentials-provider-command=<COMMAND> Runs an external command, which must return an OAuth Access Token [no default].
--spring.cloud.skipper.client.skip-ssl-validation=<true|false> Accept any SSL certificate (even self-signed) [default: no].
--spring.shell.historySize=<SIZE> Default size of the shell log file [default: 3000].
--spring.shell.commandFile=<FILE> Skipper Shell read commands read from the file(s) and then exits.
--help This message.
12.1. Shell 模式
shell 可以在交互或非交互模式下启动。
在非交互模式下,命令行参数作为 Skipper 命令运行,然后 shell 退出。
如果有任何参数没有前缀spring.cloud.skipper.client
,它们被视为要运行的 skipper 命令。
请考虑以下示例:
java -jar spring-cloud-skipper-shell-2.11.5.jar --spring.cloud.skipper.client.serverUri=http://localhost:9123/api
前面的示例打开交互式 shell 并连接到localhost:9123/api
.
现在考虑以下命令:
$ java -jar spring-cloud-skipper-shell-2.11.5.jar --spring.cloud.skipper.client.serverUri=http://localhost:9123/api search
上述命令连接到localhost:9123/api
中运行search
命令,然后退出。
更常见的用例是从 CI 作业中更新软件包,例如,在 Jenkins 阶段,如以下示例所示:
stage ('Build') {
steps {
checkout([
$class: 'GitSCM',
branches: [
[name: "*/master"]
],
userRemoteConfigs: [
[url: "https://github.com/markpollack/skipper-samples.git"]
]
])
sh '''
VERSION="1.0.0.M1-$(date +%Y%m%d_%H%M%S)-VERSION"
mvn org.codehaus.mojo:versions-maven-plugin:2.3:set -DnewVersion="${VERSION}"
mvn install
java -jar /home/mpollack/software/skipper.jar upgrade --package-name helloworld --release-name helloworld-jenkins --properties version=${VERSION}
'''
}
}
13. 平台
Skipper 支持部署到多个平台。
包含的平台包括 Local、Cloud Foundry 和 Kubernetes。
对于每个平台,您可以配置多个账户。
每account name
必须在所有平台上全局唯一。
通常,不同accounts
对应于 Cloud Foundry 的不同组织或空间,以及单个 Kubernetes 集群的不同命名空间。
平台是使用 Spring Boot 的 Externalized Configuration 功能定义的。
为了简化入门体验,如果您的配置中未定义本地平台账户,Skipper 会创建一个local
名为default
.
您可以使用 Spring Cloud Config 的加密和解密功能作为保护凭据的一种方式。
与 Skipper 部署应用程序的位置不同,您还可以在平台上运行 Skipper 服务器本身。 安装部分介绍了在其他平台上的安装。
以下示例 YAML 文件显示了所有三个平台的配置:
spring: cloud: skipper: server: platform: local: accounts: localDevDebug: javaOpts: "-Xdebug" cloudfoundry: accounts: cf-dev: connection: url: https://api.run.pivotal.io org: scdf-ci space: space-mark domain: cfapps.io username: <your-username> password: <your-password> skipSslValidation: false deployment: deleteRoutes: false kubernetes: accounts: minikube: namespace: default
可以在以下类中找到每个平台可用的属性:
-
CloudFoundryDeploymentProperties 的
deployment:
和 CloudFoundryConnectionPropertiesconnection:
.
14. 软件包
包包含安装应用程序或应用程序组所需的所有信息。 描述应用程序的方法是使用 YAML 文件,该文件提供所有必要的信息来提供帮助 便于搜索托管在 Package Registry 中的应用程序,并将应用程序安装到 平台。
为了便于自定义包,对 YAML 文件进行了模板化。
YAML 文件的最终版本(所有值都被替换)称为 releasemanifest
.
Skipper 目前了解如何基于 YAML 文件部署应用程序,该文件包含所需的信息
用于部署应用程序的 Spring Cloud Deployer 或 Cloud Foundry 实现。
它描述了在何处查找应用程序(HTTP、Maven 或 Docker 位置)、应用程序属性(想想 Spring
靴子@ConfigurationProperties
) 和部署属性 (例如要使用的内存量) 。
14.1. 包格式
包是 YAML 文件的集合,这些文件被压缩到具有以下命名约定的文件中:[PackageName]-[PackageVersion].zip
(例如:mypackage-1.0.0.zip
).
一个包可以定义单个应用程序或一组应用程序。
14.1.1. 单个应用程序
单个应用程序包文件mypackage-1.0.0.zip
,解压后,应具有以下目录
结构:
mypackage-1.0.0
├── package.yml
├── templates
│ └── template.yml
└── values.yml
这package.yml
文件包含有关包的元数据,用于支持 Skipper 的搜索功能。
这template.yml
文件包含在values.yml
文件。
安装包时,还可以指定占位符值,这些值将覆盖values.yml
文件。
Skipper 使用的模板引擎是 JMustache。
YAML 文件可以具有.yml
或.yaml
扩展。
helloworld-1.0.0.zip 或 helloworld-docker-1.0.0.zip 文件是很好的示例,可以用作 “'hand '” 创建自己的包的基础。
的源代码helloworld
示例可以在这里找到。
14.1.2. 多个应用程序
一个软件包可以包含捆绑在其中的一组应用程序。 在这些情况下,包的结构将类似于以下内容:
mypackagegroup-1.0.0
├── package.yml
├── packages
│ ├── app1
│ │ ├── package.yml
│ │ ├── templates
│ │ │ └── log.yml
│ │ └── values.yml
│ └── app2
│ ├── package.yml
│ ├── templates
│ │ └── time.yml
│ └── values.yml
└── values.yml
在前面的示例中,mypackagegroup
还是有自己的package.yml
和values.yml
指定包
metadata 和要覆盖的值。所有应用程序都位于mypackagegroup
被视为
子包,并遵循类似于单个包的包结构。需要指定这些子包
在packages
根包的目录下,mypackagegroup
.
ticktock-1.0.0.zip 文件是一个很好的示例,可以用作“手动”创建自己的包的基础。
模板类型为 CloudFoundryApplication 的包目前不支持多个应用程序格式。 |
14.2. 包元数据
这package.yml
file 指定包元数据。
示例包元数据类似于以下内容:
# Required Fields apiVersion: skipper.spring.io/v1 kind: SkipperPackageMetadata name: mypackage version: 1.0.0 # Optional Fields packageSourceUrl: https://github.com/some-mypackage-project/v1.0.0.RELEASE packageHomeUrl: https://some-mypackage-project/ tags: skipper, mypackage, sample maintainer: https://github.com/maintainer description: This is a mypackage sample.
必填字段:
-
apiVersion
:此文件所基于的 Package Index 规范版本。 -
kinds
:正在使用的包系统类型。 -
name
:包的名称。 -
version
:包的版本。
目前仅支持的 kind 是 SkipperPackageMetadata。 |
可选字段:
-
packageSourceUrl
:此包的源代码的位置。 -
packageHomeUrl
:包的主页。 -
tags
:用于搜索的标记的逗号分隔列表。 -
maintainer
:谁维护此包。 -
description
:描述包功能的自由格式文本 — 通常显示在搜索结果中。 -
sha256
:包二进制文件的哈希值(尚未强制执行)。 -
iconUrl
:要为此包显示的图标的 URL。 -
origin
:描述此包来源的自由格式文本 — 例如,您的公司名称。
目前,包搜索功能只是与包名称的通配符匹配。 |
Package Repository 公开了一个index.yml
包含多个元数据文档并使用标准的三虚线表示法分隔文档的文件,例如 index.yml。---
14.3. 包模板
目前,支持两种类型的应用程序。一个具有SpringCloudDeployerApplication
kind 的
只有使用相应的 Spring Cloud Deployer 才能将应用程序部署到目标平台中
实现(CF、Kubernetes Deployer 等)。其他是有CloudFoundryApplication
kind 的
使用其清单支持将应用程序直接部署到 Cloud Foundry 中。
14.3.1. Spring Cloud 部署程序
这template.yml
file 的包结构类似于以下示例:
mypackage-1.0.0
├── package.yml
├── templates
│ └── template.yml
└── values.yml
实际的模板文件名无关紧要,您可以有多个模板文件。这些只需要位于 |
# template.yml
apiVersion: skipper.spring.io/v1
kind: SpringCloudDeployerApplication
metadata:
name: mypackage
type: sample
spec:
resource: maven://org.mysample:mypackage
resourceMetadata: maven://org.mysample:mypackage:jar:metadata:{{spec.version}}
version: {{spec.version}}
applicationProperties:
{{#spec.applicationProperties.entrySet}}
{{key}}: {{value}}
{{/spec.applicationProperties.entrySet}}
deploymentProperties:
{{#spec.deploymentProperties.entrySet}}
{{key}}: {{value}}
{{/spec.deploymentProperties.entrySet}}
这apiVersion
,kind
和spec.resource
是必需的。
这spec.resource
和spec.version
定义应用程序可执行文件的位置。这spec.resourceMetadata
字段定义 Spring Boot Configuration 元数据 jar 的位置,其中包含应用程序的配置属性。这是一个 Spring Boot uber jar
托管在 HTTP 终端节点或 Maven 或 Docker 存储库下。模板占位符{{spec.version}}
存在,以便
可以轻松升级特定应用程序的版本,而无需创建新的软件包.zip文件。
这resource
基于http://
或maven://
或docker:
.用于指定resource
遵循记录
在 Resources 中键入。
14.3.2. Cloud Foundry
这template.yml
file 的包结构类似于以下示例:
mypackage-1.0.0
├── package.yml
├── templates
│ └── template.yml
└── values.yml
template.yml
通常包含类似于以下内容的内容:
实际的模板文件名无关紧要,您可以有多个模板文件。这些只需要位于 |
# template.yml
apiVersion: skipper.spring.io/v1
kind: CloudFoundryApplication
spec:
resource: maven://org.mysample:mypackage
version: {{spec.version}}
manifest:
{{#spec.manifest.entrySet}}
{{key}}: {{value}}
{{/spec.manifest.entrySet}}
其中 values 可以是这样的:
# values.yml
spec:
version: 1.0.0
manifest:
memory: 1024
disk-quota: 1024
的可能值spec.manifest
是:
钥匙 | 值 | 笔记 |
---|---|---|
|
(字符串) |
buildpack 属性。 |
|
(字符串) |
command 属性。 |
|
(字符串或整数) |
memory 属性,如果 type 为 Integer,则 String 在 CF 中使用相同的格式进行转换,例如 |
|
(字符串或整数) |
disk_quota type 为 Integer 时,String 在 CF 中使用相同的格式进行转换,例如 |
|
(整数) |
timeout 属性。 |
|
(整数) |
instances 属性。 |
|
(布尔值) |
no-hostname 属性。 |
|
(布尔值) |
no-route 属性。 |
|
(布尔值) |
random-route 属性。 |
|
(字符串) |
health-check-type 的可能值为 |
|
(字符串) |
health-check-http-endpoint 属性。 |
|
(字符串) |
stack 属性。 |
|
(列表<字符串>) |
services 属性。 |
|
(列表<字符串>) |
domains 属性。 |
|
(列表<字符串>) |
hosts 属性。 |
|
(地图<String,Object>) |
env 属性。 |
请记住,当从命令行给出值时,将按照模板中的定义进行替换。使用模板
格式 |
这resource
基于http://
或maven://
或docker:
.用于指定resource
遵循记录
在 Resources 中键入。
14.3.3. 资源
本部分包含当前支持的资源类型。
HTTP 资源
以下示例显示了 HTTP 的典型规范:
spec:
resource: https://example.com/app/hello-world
version: 1.0.0.RELEASE
基于 HTTP 的资源必须遵循一个命名约定,以便 Skipper 可以从resource
和version
字段,并解析给定 URL 的版本号。
前面的spec
引用位于example.com/app/hello-world-1.0.0.RELEASE.jar
.
这resource
和version
字段的字符后不应包含任何数字。-
Docker 资源
以下示例显示了 Docker 的典型规范:
spec:
resource: docker:springcloud/spring-cloud-skipper-samples-helloworld
version: 1.0.0.RELEASE
到 docker 注册表名称的映射如下:
spec:
resource: docker:<user>/<repo>
version: <tag>
Maven 资源
以下示例显示了 Maven 的典型规范:
spec: resource: maven://org.springframework.cloud.samples:spring-cloud-skipper-samples-helloworld:1.0.0.RELEASE version: 1.0.0.RELEASE
到 Maven 对象名称的映射如下
spec:
resource: maven://<maven-group-name>:<maven-artifact-name>
version:<maven-version>
只需指定一个设置即可搜索 Maven 存储库。 此设置适用于所有平台账户。 默认情况下,使用以下配置:
maven:
remoteRepositories:
springRepo: https://repo.spring.io/snapshot
您可以指定其他条目,也可以指定代理属性。
目前,此处对此进行了最好的记录。
实质上,这需要在 Launch 属性中设置为属性,或者manifest.yml
(推送到 PCF 时),如下所示:
# manifest.yml
...
env:
SPRING_APPLICATION_JSON: '{"maven": { "remote-repositories": { "springRepo": { "url": "https://repo.spring.io/snapshot"} } } }'
...
metadata 部分用于帮助搜索安装后的应用程序。 此功能将在将来的版本中提供。
这spec
包含资源规范和包的属性。
这resource
表示要从中下载应用程序的资源 URI。
这通常是 Maven 坐标或 Docker 图像 URL。
这SpringCloudDeployerApplication
类型的应用程序可以具有applicationProperties
和deploymentProperties
作为配置属性。
应用程序属性对应于应用程序本身的属性。
部署属性对应于 Spring Cloud Deployer 执行的部署作的属性 实现。
这 |
14.4. 包值
这values.yml
file 包含模板文件中指定的任何键的默认值。
例如,在定义一个应用程序的包中,格式如下所示:
version: 1.0.0.RELEASE
spec:
applicationProperties:
server.port: 9090
如果软件包定义了多个应用程序,请在顶级 YML 部分中提供软件包的名称,以限定spec
部分。考虑具有以下布局的多应用程序包的示例:
ticktock-1.0.0/
├── packages
│ ├── log
│ │ ├── package.yml
│ │ └── values.yml
│ └── time
│ ├── package.yml
│ └── values.yml
├── package.yml
└── values.yml
顶级values.yml
文件可能类似于以下内容:
#values.yml
hello: world
time:
appVersion: 1.3.0.M1
deployment:
applicationProperties:
log.level: WARN
trigger.fixed-delay: 1
log:
deployment:
count: 2
applicationProperties:
log.level: WARN
log.name: skipperlogger
前面的values.yml
文件集hello
作为变量,可用作packages\log\values.yml
文件和packages\time\values.yml
.但是,下面的 YML 部分time:
已应用
仅对packages\time\values.yml
文件以及log:
仅应用于packages\log\values.yml
文件。
14.5. 包上传
在上一节所示的结构中创建包后,我们可以使用以下命名方案将其压缩为 zip 文件: [PackageName]-[PackageVersion].zip(例如,mypackage-1.0.0.zip)。
例如,压缩前的包目录将类似于以下内容:
mypackage-1.0.0 ├── package.yml ├── templates │ └── template.yml └── values.yml
zip 文件可以上传到 Skipper 服务器的本地存储库之一。
默认情况下,Skipper 服务器有一个名为local
.
通过使用 Skipper shell,我们可以将包 zip 文件上传到 Skipper 服务器的本地仓库中,如下所示:
skipper:>package upload --path /path-to-package/mypackage-1.0.0.zip
Package uploaded successfully:[mypackage:1.0.0]
如果没有--repo-name
设置后,则upload
命令用途local
作为要上传的存储库。
然后,我们可以使用package list
或package search
命令查看我们的包是否已上传,如以下示例所示(及其输出):
skipper:>package list
╔═════════════════╤═══════╤════════════════════════════════════════════════════════════════════════════════╗
║ Name │Version│ Description ║
╠═════════════════╪═══════╪════════════════════════════════════════════════════════════════════════════════╣
║helloworld │1.0.0 │The app has two endpoints, /about and /greeting in English. Maven resource. ║
║helloworld │1.0.1 │The app has two endpoints, /about and /greeting in Portuguese. Maven resource. ║
║helloworld-docker│1.0.0 │The app has two endpoints, /about and /greeting in English. Docker resource. ║
║helloworld-docker│1.0.1 │The app has two endpoints, /about and /greeting in Portuguese. Docker resource.║
║mypackage │1.0.0 │This is a mypackage sample ║
╚═════════════════╧═══════╧════════════════════════════════════════════════════════════════════════════════╝
14.6. 创建您自己的软件包
在本节中,我们将创建一个可以使用 Spring Cloud Deployer 实现进行部署的包。
对于此包,我们将创建一个简单的包并将其上传到我们的本地计算机。
要开始创建自己的包,请按照[package-name]-[package-version]
.在我们的例子中,文件夹名称为demo-1.0.0
.
在此目录中,创建名为values.yml
和package.yml
并创建一个templates
目录。
在templates
目录中,创建一个名为template.yml
.
进入package.yml
我们将在此处指定包元数据。对于此应用程序,我们只填充可能的最小值,如以下示例所示:
# package.yml apiVersion: skipper.spring.io/v1 kind: SkipperPackageMetadata name: demo version: 1.0.0 description: Greets the world!
确保您的name 和version 匹配name 和version ,否则会收到错误。 |
接下来,打开templates/template.yml
文件。
在这里,我们将指定有关您的包的实际信息,最重要的是,设置默认值。
在template.yml
中,复制 kindSpringCloudDeployerApplication
从前面的示例中。
您的结果template.yml
文件应类似于以下内容:
# templates/template.yml apiVersion: skipper.spring.io/v1 kind: SpringCloudDeployerApplication metadata: name: demo spec: resource: maven://org.springframework.cloud.samples:spring-cloud-skipper-samples-helloworld version: {{version}} applicationProperties: {{#spec.applicationProperties.entrySet}} {{key}}: {{value}} {{/spec.applicationProperties.entrySet}} deploymentProperties: {{#spec.deploymentProperties.entrySet}} {{key}}: {{value}} {{/spec.deploymentProperties.entrySet}}
前面的示例文件指定我们的应用程序名称为demo
并在 Maven 中找到我们的包。
现在我们可以指定version
,applicationProperties
和deploymentProperties
在我们的values.yml
如下:
# values.yml # This is a YAML-formatted file. # Declare variables to be passed into your templates version: 1.0.0.RELEASE spec: applicationProperties: server.port: 8100
前面的示例将version
自1.0.0.RELEASE
,并将server.port=8100
作为应用程序属性之一。
当 Skipper Package 读取器通过合并values.yml
对于模板,resolved (解析) 的值类似于以下内容:
# hypothetical template.yml apiVersion: skipper.spring.io/v1 kind: SpringCloudDeployerApplication metadata: name: demo spec: resource: maven://org.springframework.cloud.samples:spring-cloud-skipper-samples-helloworld version: 1.0.0.RELEASE applicationProperties: server.port: 8100 deploymentProperties:
使用的理由values.yml
而不是直接输入值,而是允许您在运行时使用--file
或--properties
标志。
我们已经完成了文件制作。
现在我们必须把它拉上拉链。
最简单的方法是使用zip -r
命令,如下所示:
$ zip -r demo-1.0.0.zip demo-1.0.0/ adding: demo-1.0.0/ (stored 0%) adding: demo-1.0.0/package.yml (deflated 14%) adding: demo-1.0.0/templates/ (stored 0%) adding: demo-1.0.0/templates/template.yml (deflated 55%) adding: demo-1.0.0/values.yml (deflated 4%)
有了我们的压缩文件及其路径,我们可以前往 Skipper 并使用upload
命令,如下所示:
skipper:>package upload --path /Users/path-to-your-zip/demo-1.0.0.zip Package uploaded successfully:[demo:1.0.0]
现在,您可以按前面所示搜索它,然后安装它,如下所示
skipper:>package install --package-name demo --package-version 1.0.0 --release-name demo Released demo. Now at version v1.
祝贺!您现在已经创建、打包、上传和安装了自己的 Skipper 包!
15. 存储库
存储库存储包元数据和托管包.zip文件。 存储库可以是本地的或远程的,本地是指由 Skipper 的关系数据库支持,远程是指通过 HTTP 公开的文件系统。
注册远程注册表时(例如,experimental
除了名为 local' 的 one) 之外,当前默认未定义的 one),请使用以下格式:
spring cloud: skipper: server: package-repositories: experimental: url: https://skipper-repository.cfapps.io/repository/experimental description: Experimental Skipper Repository repoOrder: 0 local: url: http://${spring.cloud.client.hostname}:7577 local: true description: Default local database backed repository repoOrder: 1
对于 Skipper 2.x,spring.cloud.skipper.server.package-repositories 结构已从列表更改为映射,其中 key 是存储库名称。使用 map 格式可以更轻松地定义和覆盖配置值。 |
这repoOrder
确定在两个或多个存储库中注册了具有相同名称的软件包时,哪个存储库提供软件包。
远程仓库采用的目录结构是已注册的url
值,后跟软件包名称,然后是 zip 文件名(例如skipper-repository.cfapps.io/repository/experimental/helloworld/helloworld-1.0.0.zip
对于包装helloworld
使用1.0.0
).
名为index.yml
应直接隶属于注册的url
— 例如,skipper-repository.cfapps.io/repository/experimental/index.yml。
此文件包含存储库托管的所有包的包元数据。
您需要更新index.yml
文件 “'by hand'” 用于远程仓库。
“本地”存储库由 Skipper 的数据库提供支持。 在 Skipper 1.0 版本中,它们不会像远程存储库那样在类似文件系统的 URL 结构下公开 index.yml 或 .zip 文件。 此功能将在下一个版本中提供。 但是,您可以将包上传到本地存储库,并且不需要维护索引文件。 有关创建本地存储库的信息,请参阅“Skipper 命令”部分。
可以在此处找到一个很好的示例,该示例显示了使用具有静态资源的 Spring Boot Web 应用程序来托管存储库。 此应用程序当前在 skipper-repository.cfapps.io/repository/experimental 下运行。