Указание ресурсов в манифесте службы
Обзор
Для определения и управления версиями служб и приложений в Service Fabric применяются файлы манифеста. Обобщенный обзор ServiceManifest.xml и ApplicationManifest.xml см. в статье Манифесты службы и приложения Service Fabric.
Манифест служб позволяет объявлять или изменять ресурсы, используемые в службе, не меняя скомпилированный код. Service Fabric поддерживает настройку ресурсов конечных точек для службы. Доступ к ресурсам, указанным в манифесте служб, можно контролировать в манифесте приложения с помощью элемента SecurityGroup. Объявление ресурсов позволяет изменять их при развертывании, т. е. службе не нужно внедрять новый механизм настройки. Определение схемы для файла ServiceManifest.xml устанавливается вместе с пакетом SDK и средствами для Service Fabric в каталог C:\Program Files\Microsoft SDKs\Service Fabric\schemas\ServiceFabricServiceModel.xsd, а документация по этой схеме опубликована здесь.
Конечные точки
Если ресурс конечной точки определен в манифесте службы, Service Fabric назначает порты из диапазона зарезервированных портов приложений, если порт не указан явным образом. Например, рассмотрим конечную точку ServiceEndpoint1 , которая указана во фрагменте кода манифеста, приведенном после абзаца. Кроме того, службы также могут запрашивать наличие в ресурсе конкретного порта. Репликам службы, которые выполняются на различных узлах кластера, можно назначить разные номера портов, а реплики службы, выполняющиеся на одном и том же узле, будут совместно используют один порт. Реплики службы при необходимости могут использовать эти порты для репликации и прослушивания клиентских запросов.
При активации службы, которая определяет конечную точку HTTPS, Service Fabric настроит запись управления доступом для порта, привяжет к этому порту указанный сертификат сервера и выделит службе удостоверение, которое предоставляет разрешения на использование закрытого ключа сертификата. Этот поток активации вызывается при каждом запуске Service Fabric и при изменении объявления сертификата приложения в процессе обновления. Также отслеживаются изменения и обновления сертификата конечной точки и периодически, по мере необходимости, повторно предоставляются разрешения.
После завершения работы службы Service Fabric очистит запись управления доступом для конечной точки и удалит привязку сертификата. Но разрешения, примененные к закрытому ключу этого сертификата, не очищаются.
Предупреждение
Используемая архитектура требует, чтобы статические порты не перекрывались с диапазоном портов приложений, указанным в ClusterManifest. Указывая статический порт, не используйте номера из диапазона портов приложения, поскольку это приведет к конфликтам портов. В выпуске 6.5 CU2 мы создаем предупреждение о работоспособности при обнаружении таких конфликтов, но работа развертывания при этом продолжается так же, как в уже выпущенной версии 6.5. Возможно, в одном из следующих основных выпусков развертывание приложения будет в такой ситуации блокироваться.
В выпуске 7.0 мы создаем предупреждение о работоспособности, если диапазон портов приложения превышает ограничение HostingConfig::ApplicationPortExhaustThresholdPercentage (по умолчанию это 80 %).
<Resources>
<Endpoints>
<Endpoint Name="ServiceEndpoint1" Protocol="http"/>
<Endpoint Name="ServiceEndpoint2" Protocol="http" Port="80"/>
<Endpoint Name="ServiceEndpoint3" Protocol="https"/>
</Endpoints>
</Resources>
Если в одном пакете службы несколько пакетов кода, на пакет кода также нужно добавить ссылку в разделе Конечные точки. Например, если ServiceEndpoint2a и ServiceEndpoint2b являются конечными точками из одного и того же пакета службы и ссылаются на разные пакеты кода, пакет кода, который соответствует каждой конечной точке, определяется, как показано ниже:
<Resources>
<Endpoints>
<Endpoint Name="ServiceEndpoint2a" Protocol="http" Port="802" CodePackageRef="Code1"/>
<Endpoint Name="ServiceEndpoint2b" Protocol="http" Port="801" CodePackageRef="Code2"/>
</Endpoints>
</Resources>
Дополнительные сведения о создании ссылок на конечные точки из файла параметров пакета конфигурации (settings.xml) см. в статье Настройка надежных служб с отслеживанием состояния.
Пример. Указание конечной точки HTTP для службы
Следующий манифест служб в элементе <Resources> определяет один ресурс конечной точки TCP и два ресурса конечной точки HTTP.
<?xml version="1.0" encoding="utf-8"?>
<ServiceManifest Name="Stateful1Pkg"
Version="1.0.0"
xmlns="http://schemas.microsoft.com/2011/01/fabric"
xmlns:xsd="https://www.w3.org/2001/XMLSchema"
xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">
<ServiceTypes>
<!-- This is the name of your ServiceType.
This name must match the string used in the RegisterServiceType call in Program.cs. -->
<StatefulServiceType ServiceTypeName="Stateful1Type" HasPersistedState="true" />
</ServiceTypes>
<!-- Code package is your service executable. -->
<CodePackage Name="Code" Version="1.0.0">
<EntryPoint>
<ExeHost>
<Program>Stateful1.exe</Program>
</ExeHost>
</EntryPoint>
</CodePackage>
<!-- Config package is the contents of the Config directory under PackageRoot that contains an
independently updateable and versioned set of custom configuration settings for your service. -->
<ConfigPackage Name="Config" Version="1.0.0" />
<Resources>
<Endpoints>
<!-- This endpoint is used by the communication listener to obtain the port number on which to
listen. Note that if your service is partitioned, this port is shared with
replicas of different partitions that are placed in your code. -->
<Endpoint Name="ServiceEndpoint1" Protocol="http"/>
<Endpoint Name="ServiceEndpoint2" Protocol="http" Port="80"/>
<Endpoint Name="ServiceEndpoint3" Protocol="https"/>
<Endpoint Name="ServiceEndpoint4" Protocol="https" Port="14023"/>
<!-- This endpoint is used by the replicator for replicating the state of your service.
This endpoint is configured through the ReplicatorSettings config section in the Settings.xml
file under the ConfigPackage. -->
<Endpoint Name="ReplicatorEndpoint" />
</Endpoints>
</Resources>
</ServiceManifest>
Пример. Указание конечной точки HTTPS для службы
Протокол HTTPS обеспечивает аутентификацию сервера, а также используется для шифрования данных, передаваемых между клиентом сервером. Чтобы включить протокол HTTPS в службе Service Fabric, укажите его в разделе Ресурсы > Конечные точки > Конечная точка манифеста служб, как показано выше для конечной точки ServiceEndpoint3.
Примечание
Протокол службы невозможно изменить при обновлении приложения. Если изменить его во время обновления, то это будет считаться критическим изменением.
Предупреждение
При использовании HTTPS не используйте тот же порт и сертификат для разных экземпляров службы (независимо от приложения), развернутых на одном узле. Обновление двух разных служб, использующих один порт в разных экземплярах приложения, приведет к сбою обновлений. Дополнительные сведения. см в статье Обновление нескольких приложений с помощью конечных точек HTTPS.
Ниже приведен пример файла ApplicationManifest с требуемой конфигурацией для конечной точки HTTPS. Сертификат сервера или конечной точки может быть объявлен по отпечатку или по общему имени субъекта, и для него должно быть указано значение. EndpointRef содержит ссылку на EndpointResource, определенный в ServiceManifest, для которого должен быть задан протокол HTTPS. Можно добавить несколько элементов Endpointcertificate.
<?xml version="1.0" encoding="utf-8"?>
<ApplicationManifest ApplicationTypeName="Application1Type"
ApplicationTypeVersion="1.0.0"
xmlns="http://schemas.microsoft.com/2011/01/fabric"
xmlns:xsd="https://www.w3.org/2001/XMLSchema"
xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance">
<Parameters>
<Parameter Name="Stateful1_MinReplicaSetSize" DefaultValue="3" />
<Parameter Name="Stateful1_PartitionCount" DefaultValue="1" />
<Parameter Name="Stateful1_TargetReplicaSetSize" DefaultValue="3" />
</Parameters>
<!-- Import the ServiceManifest from the ServicePackage. The ServiceManifestName and ServiceManifestVersion
should match the Name and Version attributes of the ServiceManifest element defined in the
ServiceManifest.xml file. -->
<ServiceManifestImport>
<ServiceManifestRef ServiceManifestName="Stateful1Pkg" ServiceManifestVersion="1.0.0" />
<ConfigOverrides />
<Policies>
<EndpointBindingPolicy CertificateRef="SslCertByTP" EndpointRef="ServiceEndpoint3"/>
<EndpointBindingPolicy CertificateRef="SslCertByCN" EndpointRef="ServiceEndpoint4"/>
</Policies>
</ServiceManifestImport>
<DefaultServices>
<!-- The section below creates instances of service types when an instance of this
application type is created. You can also create one or more instances of service type by using the
Service Fabric PowerShell module.
The attribute ServiceTypeName below must match the name defined in the imported ServiceManifest.xml file. -->
<Service Name="Stateful1">
<StatefulService ServiceTypeName="Stateful1Type" TargetReplicaSetSize="[Stateful1_TargetReplicaSetSize]" MinReplicaSetSize="[Stateful1_MinReplicaSetSize]">
<UniformInt64Partition PartitionCount="[Stateful1_PartitionCount]" LowKey="-9223372036854775808" HighKey="9223372036854775807" />
</StatefulService>
</Service>
</DefaultServices>
<Certificates>
<EndpointCertificate Name="SslCertByTP" X509FindValue="FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF F0" X509StoreName="MY" />
<EndpointCertificate Name="SslCertByCN" X509FindType="FindBySubjectName" X509FindValue="ServiceFabric-EndpointCertificateBinding-Test" X509StoreName="MY" />
</Certificates>
</ApplicationManifest>
Для кластеров Linux MY сохраняет значения по умолчанию в папку /var/lib/sfcerts.
Пример полного приложения, которое использует конечную точку HTTPS, можно изучить в статье Добавление конечной точки HTTPS в интерфейсную службу веб-API ASP.NET Core с использованием Kestrel.
Применение списков управления доступом к портам для конечных точек HTTP
По умолчанию Service Fabric будет автоматически применять списки управления доступом к определенным конечным точкам HTTP(S). Но служба не будет автоматически применять список управления доступом, если с конечной точкой не связана политика SecurityAccessPolicy и для выполнения Service Fabric настроена учетная запись с правами администратора.
Переопределение конечных точек в файле ServiceManifest.xml
Добавьте в файл ApplicationManifest раздел ResourceOverrides на одном уровне с разделом ConfigOverrides. В этом разделе можно задать параметры переопределения для раздела конечных точек в разделе ресурсов, указанном в манифесте служб. Переопределение конечных точек поддерживается в среде выполнения 5.7.217 и пакете SDK 2.7.217 и более поздних версий.
Чтобы переопределить EndPoint в ServiceManifest, используя ApplicationParameters, измените ApplicationManifest, как описано ниже.
Добавьте новый подраздел ResourceOverrides в раздел ServiceManifestImport.
<ServiceManifestImport>
<ServiceManifestRef ServiceManifestName="Stateless1Pkg" ServiceManifestVersion="1.0.0" />
<ConfigOverrides />
<ResourceOverrides>
<Endpoints>
<Endpoint Name="ServiceEndpoint" Port="[Port]" Protocol="[Protocol]" Type="[Type]" />
<Endpoint Name="ServiceEndpoint1" Port="[Port1]" Protocol="[Protocol1] "/>
</Endpoints>
</ResourceOverrides>
<Policies>
<EndpointBindingPolicy CertificateRef="SslCertByTP" EndpointRef="ServiceEndpoint"/>
</Policies>
</ServiceManifestImport>
В раздел Parameters добавьте следующее:
<Parameters>
<Parameter Name="Port" DefaultValue="" />
<Parameter Name="Protocol" DefaultValue="" />
<Parameter Name="Type" DefaultValue="" />
<Parameter Name="Port1" DefaultValue="" />
<Parameter Name="Protocol1" DefaultValue="" />
</Parameters>
При развертывании приложения эти значения можно передать в разделе ApplicationParameters. Пример:
PS C:\> New-ServiceFabricApplication -ApplicationName fabric:/myapp -ApplicationTypeName "AppType" -ApplicationTypeVersion "1.0.0" -ApplicationParameter @{Port='1001'; Protocol='https'; Type='Input'; Port1='2001'; Protocol='http'}
Примечание. Если для параметра ApplicationParameter не указано значение, применяется значение по умолчанию, предоставленное в ServiceManifest для соответствующей конечной точки.
Пример:
Допустим, в ServiceManifest заданы следующие значения:
<Resources>
<Endpoints>
<Endpoint Name="ServiceEndpoint1" Protocol="tcp"/>
</Endpoints>
</Resources>
Допустим, что в параметрах приложения Port1 и Protocol1 имеют значение NULL или не заданы. Тогда порт назначается службой ServiceFabric и применяется протокол TCP.
Предположим, что вы задали неверное значение. Допустим, для параметра Port вы указали вместо целого числа строковое значение "Foo". Тогда команда New-ServiceFabricApplication завершится ошибкой: The override parameter with name 'ServiceEndpoint1' attribute 'Port1' in section 'ResourceOverrides' is invalid. The value specified is 'Foo' and required is 'int'.
Next Steps
В этой статье объясняется, как определить конечные точки в манифесте службы Service Fabric. Более подробные примеры см. в следующей статье.
Пошаговое руководство по упаковке и развертыванию существующего приложения в кластере Service Fabric см. в следующей статье.