TemplateManager.java

// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.
package com.cloud.template;

import java.util.List;
import java.util.Set;

import org.apache.cloudstack.api.BaseCmd;
import org.apache.cloudstack.engine.subsystem.api.storage.DataStore;
import org.apache.cloudstack.engine.subsystem.api.storage.TemplateInfo;
import org.apache.cloudstack.framework.config.ConfigKey;
import org.apache.cloudstack.storage.datastore.db.StoragePoolVO;

import com.cloud.agent.api.to.DatadiskTO;
import com.cloud.dc.DataCenterVO;
import com.cloud.deploy.DeployDestination;
import com.cloud.exception.ResourceAllocationException;
import com.cloud.exception.StorageUnavailableException;
import com.cloud.hypervisor.Hypervisor;
import com.cloud.storage.DataStoreRole;
import com.cloud.storage.Storage.TemplateType;
import com.cloud.storage.StoragePool;
import com.cloud.storage.VMTemplateStoragePoolVO;
import com.cloud.storage.VMTemplateVO;
import com.cloud.storage.VolumeVO;
import com.cloud.utils.Pair;
import com.cloud.vm.VirtualMachine;
import com.cloud.vm.VirtualMachineProfile;

/**
 * TemplateManager manages the templates stored on secondary storage. It is responsible for creating private/public templates.
 */
public interface TemplateManager {
    static final String AllowPublicUserTemplatesCK = "allow.public.user.templates";
    static final String TemplatePreloaderPoolSizeCK = "template.preloader.pool.size";
    static final String PublicTemplateSecStorageCopyCK = "secstorage.public.template.copy.max";
    static final String PrivateTemplateSecStorageCopyCK = "secstorage.private.template.copy.max";

    static final ConfigKey<Boolean> AllowPublicUserTemplates = new ConfigKey<Boolean>("Advanced", Boolean.class, AllowPublicUserTemplatesCK, "true",
        "If false, users will not be able to create public Templates.", true, ConfigKey.Scope.Account);

    static final ConfigKey<Integer> TemplatePreloaderPoolSize = new ConfigKey<Integer>("Advanced", Integer.class, TemplatePreloaderPoolSizeCK, "8",
            "Size of the TemplateManager threadpool", false, ConfigKey.Scope.Global);

    ConfigKey<Boolean> ValidateUrlIsResolvableBeforeRegisteringTemplate = new ConfigKey<>("Advanced", Boolean.class,
            "validate.url.is.resolvable.before.registering.template", "true", "Indicates whether CloudStack "
            + "will validate if the provided URL is resolvable during the register of templates/ISOs before persisting them in the database.",
            true);

    ConfigKey<Boolean> TemplateDeleteFromPrimaryStorage = new ConfigKey<Boolean>("Advanced",
            Boolean.class,
            "template.delete.from.primary.storage", "true",
            "Template when deleted will be instantly deleted from the Primary Storage",
            true,
            ConfigKey.Scope.Global);

    ConfigKey<Integer> PublicTemplateSecStorageCopy = new ConfigKey<Integer>("Advanced", Integer.class,
            PublicTemplateSecStorageCopyCK, "0",
            "Maximum number of secondary storage pools to which a public template is copied. " +
            "0 means copy to all secondary storage pools (default behavior).",
            true, ConfigKey.Scope.Zone);

    ConfigKey<Integer> PrivateTemplateSecStorageCopy = new ConfigKey<Integer>("Advanced", Integer.class,
            PrivateTemplateSecStorageCopyCK, "1",
            "Maximum number of secondary storage pools to which a private template is copied. " +
            "Default is 1 to preserve existing behavior.",
            true, ConfigKey.Scope.Zone);

    ConfigKey<Integer> VmIsoMaxCount = new ConfigKey<Integer>("Advanced",
            Integer.class,
            "vm.iso.max.count", "1",
            "Maximum number of ISOs that may be attached to a VM.",
            true,
            ConfigKey.Scope.Cluster);

    // KVM/libvirt maps deviceSeq=3 to hdc (hda/hdb are taken by the root volume on i440fx/IDE).
    // user_vm.iso_id has always pointed at this slot; additional cdroms live in vm_iso_map.
    int CDROM_PRIMARY_DEVICE_SEQ = 3;

    // Fallback per-VM cdrom cap when the placement host hasn't advertised host.cdrom.max.count
    // (older agent, never-deployed VM, etc.).
    int DEFAULT_CDROM_MAX_PER_VM = 1;

    static final String VMWARE_TOOLS_ISO = "vmware-tools.iso";
    static final String XS_TOOLS_ISO = "xs-tools.iso";

    /**
     * Prepares a template for vm creation for a certain storage pool.
     *
     * @param template
     *            template to prepare
     * @param pool
     *            pool to make sure the template is ready in.
     * @return VMTemplateStoragePoolVO if preparation is complete; null if not.
     */
    VMTemplateStoragePoolVO prepareTemplateForCreate(VMTemplateVO template, StoragePool pool);

    boolean resetTemplateDownloadStateOnPool(long templateStoragePoolRefId);

    /**
     * Copies a template from its current secondary storage server to the secondary storage server in the specified zone.
     *
     * @param template
     * @param srcSecStore
     * @param destZone
     * @return true if success
     * @throws StorageUnavailableException
     * @throws ResourceAllocationException
     */
    boolean copy(long userId, VMTemplateVO template, DataStore srcSecStore, DataCenterVO dstZone) throws StorageUnavailableException, ResourceAllocationException;

    /**
     * Deletes a template from secondary storage servers
     *
     * @param userId
     * @param templateId
     * @param zoneId
     *            - optional. If specified, will only delete the template from the specified zone's secondary storage server.
     * @return true if success
     */
    boolean delete(long userId, long templateId, Long zoneId);

    /**
     * Lists templates in the specified storage pool that are not being used by any VM.
     *
     * @param pool
     * @return list of VMTemplateStoragePoolVO
     */
    List<VMTemplateStoragePoolVO> getUnusedTemplatesInPool(StoragePoolVO pool);

    void evictTemplateFromStoragePoolsForZones(Long templateId, List<Long> zoneId);

    /**
     * Deletes a template in the specified storage pool.
     *
     * @param templatePoolVO
     */
    void evictTemplateFromStoragePool(VMTemplateStoragePoolVO templatePoolVO);

    boolean templateIsDeleteable(long templateId);

    Pair<String, String> getAbsoluteIsoPath(long templateId, long dataCenterId);

    String getSecondaryStorageURL(long zoneId);

    DataStore getImageStore(long zoneId, long tmpltId);

    DataStore getImageStore(long tmpltId);

    Long getTemplateSize(VirtualMachineTemplate template, long zoneId);

    DataStore getImageStore(String storeUuid, Long zoneId, VolumeVO volume);

    String getChecksum(DataStore store, String templatePath, String algorithm);

    List<DataStore> getImageStoreByTemplate(long templateId, Long zoneId);

    /**
     * Max number of secondary storage copies for the template in this zone; {@code 0} means no limit.
     * SYSTEM/ROUTING/BUILTIN templates are always exempt (returns {@code 0}).
     */
    int getSecStorageCopyLimit(VMTemplateVO template, long zoneId);

    TemplateInfo prepareIso(long isoId, long dcId, Long hostId, Long poolId);


    /**
     * Adds ISO definition to given vm profile
     *
     * @param VirtualMachineProfile
     */
    void prepareIsoForVmProfile(VirtualMachineProfile profile, DeployDestination dest);

    /**
     * Returns the device ids of the CD-ROM devices of the Instance, starting from {@link #CDROM_PRIMARY_DEVICE_SEQ}.
     * They cannot be used by the volumes of the Instance.
     * The hypervisor defines all the CD-ROM devices it supports for the Instance (see {@code host.cdrom.max.count}),
     * whether or not ISOs are attached to them. If the Instance uses config drive, the config drive ISO is one more
     * CD-ROM: it keeps its device id (4), and the CD-ROMs of the ISOs from that device id are moved to the next ones.
     *
     * @param vm the Instance
     * @return the device ids of the CD-ROM devices, including the one of the config drive ISO if the Instance uses config drive
     */
    Set<Long> getCdromDeviceIds(VirtualMachine vm);

    /**
     * Same as {@link #getCdromDeviceIds(VirtualMachine)}, with the specified usage of config drive instead of the one of
     * the Instance. It is useful when the networks of the Instance are not known yet, e.g. when importing it.
     */
    Set<Long> getCdromDeviceIds(VirtualMachine vm, boolean configDriveUsed);

    public static final String MESSAGE_REGISTER_PUBLIC_TEMPLATE_EVENT = "Message.RegisterPublicTemplate.Event";
    public static final String MESSAGE_RESET_TEMPLATE_PERMISSION_EVENT = "Message.ResetTemplatePermission.Event";

    TemplateType validateTemplateType(BaseCmd cmd, boolean isAdmin, boolean isCrossZones, Hypervisor.HypervisorType hypervisorType);

    DataStore verifyHeuristicRulesForZone(VMTemplateVO template, Long zoneId);

    List<DatadiskTO> getTemplateDisksOnImageStore(VirtualMachineTemplate template, DataStoreRole role, String configurationId);

    static Boolean getValidateUrlIsResolvableBeforeRegisteringTemplateValue() {
        return ValidateUrlIsResolvableBeforeRegisteringTemplate.value();
    }
}